Cookie Notice

Bamboo REST API documentation

The Bamboo REST APIs are for developers who want to integrate their application with Bamboo and for administrators who want to script interactions with the Bamboo server.

Introduction to Bamboo's REST APIs

Bamboo's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. By default, the response format is XML. If you wish, you can request JSON instead of XML.

Because the REST API is based on open standards, you can use any web development language to access the API.

A common use case would be a build service, which provides information about build results.

Bamboo's REST APIs provide the following capabilities:

Getting Started

If you would like to know more about REST in general, start with the RESTwiki's guide to REST In Plain English.

Then jump right in and try our REST resources:

Advanced Topics

Below are some links to in-depth information on development of REST APIs and plugins:

How to use expansion in the REST APIs

In order to be minimise network traffic from the client perspective, our API uses a technique called expansion.

You can use the 'expand' query parameter to specify a comma-separated list of entities that you want expanded, identifying each entity by a given identifier. For example, the value "changes,stages.stage.results.result" requests the expansion of entities for which the expand identifier is "change" and "stages".

To discover the identifiers for each entity, look at the 'expand' attribute in the parent entity. In the XML example below, the page entity declares changes, metadata, artifacts, comments, labels, jiraIssues and stages as being expandable.

Note: The 'expand' attribute should not be confused with the 'expand' query parameter which specifies which entities you want expanded.

You can use the dot notation to specify expansion of entities within another entity. For example "children.children" would expand the children and the children's children (because its expand identifier is children) and the child entities within the plugin.

If not otherwise indicated, all methods return both XML and JSON. Below are examples of the XML and JSON representations.

XML representation:

[expand]
The same content in JSON:
[expand]

Resources List

This document the current REST API provided by Bamboo.

Resources

/

Directory resource for Bamboo REST resources

Methods

GET

Provides list of available REST resources in Bamboo

available response representations:

  • 200 - application/xml, application/json (restResources) [expand]

/plan

Plan service is supposed to be used to retrieve full list of plans and plan details

Methods

GET

Method used to list all plans on Bamboo service that user is allowed to see (READ permission). Should be invoked as /rest/api/latest/plan <p/> Possible expand parameters plans - list of plans plans.plan - list of plans with plan details plans.plan.actions <p/>

available response representations:

  • application/xml (plans) [expand]
  • application/json (plans) [expand]

/plan/{projectKey}-{buildKey}

resource-wide template parameters
parameter value description

buildKey

string

projectKey

string
Methods

GET

available response representations:

  • application/xml (plan) [expand]
  • application/json (plan) [expand]

/plan/{projectKey}/{buildKey}

resource-wide template parameters
parameter value description

buildKey

string

projectKey

string
Methods

GET

available response representations:

  • application/xml (plan) [expand]
  • application/json (plan) [expand]

/plan/{projectKey}-{buildKey}/branch

resource-wide template parameters
parameter value description

buildKey

string

plan key (might be simply planKey or composite planKey-jobKey)

projectKey

string

project key
Methods

GET

Provide list of branches for specified plan. Plan might be top level plan (projectKey-planKey) or job plan (projectKey-planKey-jobKey). You can use "enabledOnly" param to filter out disabled branches.

available response representations:

  • 404 [expand]
  • 200 [expand]
  • 401 [expand]

/plan/{projectKey}-{buildKey}/branch/{branchName}

resource-wide template parameters
parameter value description

buildKey

string

plan key (might be simply planKey or composite planKey-jobKey)

branchName

string

branch display name

projectKey

string

project key
Methods

PUT

Method for creating branch for a specified plan. You can use vcsBranch query param to define which vcsBranch should newly created branch use. If not specified it will not override vcsBranch from the main plan. Example usage: curl -X PUT --user admin:admin http://localhost:8085/rest/api/latest/plan/PROJ-PLAN/branch/BranchName?vcsBranch="/refs/heads/myBranch"

available response representations:

  • 404 [expand]
  • 200 [expand]
  • 401 [expand]

GET

Provide details for specified Branch of a specified Plan. Plan might be top level plan (projectKey-planKey) or job plan (projectKey-planKey-jobKey).

available response representations:

  • 404 [expand]
  • 200 [expand]
  • 401 [expand]

/plan/{projectKey}-{buildKey}/label

resource-wide template parameters
parameter value description

buildKey

string

plan key (might be simply planKey or composite planKey-jobKey)

projectKey

string

project key
Methods

GET

Provide list of labels for plan specified by projectKey-buildKey.

available response representations:

  • 404 [expand]
  • 200 (restPlanLabelList) [expand]
  • 401 [expand]

POST

Adds new label to plan specified by projectKey-buildKey.

acceptable request representations:

  • application/xml (label) [expand]
  • application/json (label) [expand]

/plan/{projectKey}-{buildKey}/label/{labelName}

resource-wide template parameters
parameter value description

buildKey

string

plan key (might be simply planKey or composite planKey-jobKey)

labelName

string

label name to remove from plan

projectKey

string

project key
Methods

DELETE

Removes label from plan specified by projectKey-buildKey-buildNumber.

/plan/{projectKey}-{buildKey}/vcsBranches

resource-wide template parameters
parameter value description

buildKey

string

projectKey

string
Methods

GET

Provide list of vcs branch names for branches that exist on the default repository of this plan

available response representations:

  • 404 [expand]
  • 200 [expand]
  • 401 [expand]

/plan/{projectKey}-{buildKey}/issue/{issueKey}

resource-wide template parameters
parameter value description

buildKey

string

issueKey

string

projectKey

string
Methods

GET

available response representations:

  • application/xml (issue) [expand]
  • application/json (issue) [expand]

/plan/{projectKey}-{buildKey}/favourite

resource-wide template parameters
parameter value description

buildKey

string

projectKey

string
Methods

POST

available response representations:

DELETE

available response representations:

/plan/{projectKey}-{buildKey}/enable

resource-wide template parameters
parameter value description

buildKey

string

projectKey

string
Methods

POST

available response representations:

DELETE

available response representations:

/plan/{projectKey}-{buildKey}/artifact

resource-wide template parameters
parameter value description

buildKey

string

projectKey

string
Methods

GET

available response representations:

  • application/xml (artifacts) [expand]
  • application/json (artifacts) [expand]

/deploy/issue-status

Methods

/deploy/issue-status/{key}/{deploymentProjectId}

resource-wide template parameters
parameter value description

deploymentProjectId

string

key

string
Methods

GET

available response representations:

  • application/json (deploymentProjectForJiraIssue) [expand]

/deploy/issue-status/{key}

resource-wide template parameters
parameter value description

key

string
Methods

GET

available response representations:

  • application/json (jiraIssueRelatedDeploymentProjects) [expand]

/deploy/dashboard

Methods

GET

available response representations:

  • application/json (dashboardProjectWithEnvironmentStatus) [expand]

/deploy/dashboard/{projectId}

resource-wide template parameters
parameter value description

projectId

long
Methods

GET

available response representations:

  • application/json (dashboardProjectWithEnvironmentStatus) [expand]

/dependency

Methods

/dependency/{projectKey}-{buildKey}/child

resource-wide template parameters
parameter value description

buildKey

string

projectKey

string
Methods

GET

List of plan child dependencies

available response representations:

  • application/xml (dependencies) [expand]
  • application/json (dependencies) [expand]

/dependency/{projectKey}-{buildKey}/parent

resource-wide template parameters
parameter value description

buildKey

string

projectKey

string
Methods

GET

List of plan parent dependencies

available response representations:

  • application/xml (dependencies) [expand]
  • application/json (dependencies) [expand]

/dependency/search/{projectKey}-{buildKey}/child?searchTerm

resource-wide template parameters
parameter value description

buildKey

string

projectKey

string
Methods

GET

Search for available plan child dependencies

request query parameters
parameter value description

searchTerm

string

available response representations:

  • application/xml (dependencies) [expand]
  • application/json (dependencies) [expand]

/dependency/search/{projectKey}-{buildKey}/parent?searchTerm

resource-wide template parameters
parameter value description

buildKey

string

projectKey

string
Methods

GET

Search for available plan parent dependencies

request query parameters
parameter value description

searchTerm

string

available response representations:

  • application/xml (dependencies) [expand]
  • application/json (dependencies) [expand]

/deploy/environment

Methods

/deploy/environment/{environmentId}/results

resource-wide template parameters
parameter value description

environmentId

long
Methods

GET

available response representations:

/deploy/project

Methods

PUT

acceptable request representations:

  • application/json (deploymentProject) [expand]

available response representations:

  • application/json (deploymentProject) [expand]

/deploy/project/all

Methods

GET

Return all Package Definitions, including jobs.

available response representations:

/deploy/project/{id}

resource-wide template parameters
parameter value description

id

long
Methods

GET

available response representations:

  • application/json (deploymentProject) [expand]

POST

acceptable request representations:

  • application/json (deploymentProject) [expand]

available response representations:

  • application/json (deploymentProject) [expand]

/deploy/project/{projectId}/versions?branchKey

resource-wide template parameters
parameter value description

projectId

long
Methods

GET

request query parameters
parameter value description

branchKey

string

available response representations:

/deploy/project/forPlan?planKey

Methods

GET

request query parameters
parameter value description

planKey

string

available response representations:

  • application/json (restLinkedDeploymentProject) [expand]

/clone

Methods

/clone/{projectKey}-{buildKey}:{toProjectKey}-{toBuildKey}

resource-wide template parameters
parameter value description

toBuildKey

string

buildKey

string

toProjectKey

string

projectKey

string
Methods

PUT

Method used to clone an existing Plan into a new one, possibly into different project. Usage: /rest/api/latest/clone/FROM-PLAN:TO-PLAN

available response representations:

  • application/xml (plan) [expand]
  • application/json (plan) [expand]

/currentUser

Methods

GET

available response representations:

  • application/json (userBean) [expand]
  • application/xml (userBean) [expand]

/info

Methods

GET

available response representations:

  • application/xml (info) [expand]
  • application/json (info) [expand]

/chart

Methods

GET

available response representations:

  • application/xml (chart) [expand]
  • application/json (chart) [expand]

/chart/reports

Methods

GET

available response representations:

  • application/xml (reports) [expand]
  • application/json (reports) [expand]

/chart/planSummary

Methods

GET

available response representations:

  • application/xml (chart) [expand]
  • application/json (chart) [expand]

/deploy/preview

Methods

/deploy/preview/result?resultKey&planKey&buildNumber&deploymentProjectId&previousVersionId

Methods

GET

request query parameters
parameter value description

resultKey

string

planKey

string

buildNumber

int

deploymentProjectId

long

previousVersionId

long

available response representations:

  • application/json (versionPreview) [expand]

/deploy/preview/version?versionName&versionId&deploymentProjectId&previousVersionId

Methods

GET

request query parameters
parameter value description

versionName

string

versionId

long

deploymentProjectId

long

previousVersionId

long

available response representations:

  • application/json (versionPreview) [expand]

/deploy/preview/possibleResults?planKey&deploymentProjectId

Methods

GET

request query parameters
parameter value description

planKey

string

deploymentProjectId

long

available response representations:

/deploy/preview/versionName?deploymentProjectId&resultKey

Methods

GET

request query parameters
parameter value description

deploymentProjectId

long

resultKey

string

available response representations:

/capability

Methods

/capability/groupedListing?searchTerm&lastGroup

Methods

GET

Provides a list of capabilities for a select list in the UI. Filterable and paginable

request query parameters
parameter value description

searchTerm

string

lastGroup

string

available response representations:

/quicksearch?searchTerm

Methods

GET

Performs a starts with search against full plan name and full plan key. Use "type" argument to filter by plan type by default will return TopLevelPlans

request query parameters
parameter value description

searchTerm

string

to search for. Optional

available response representations:

/elasticConfiguration

Methods

GET

available response representations:

  • application/json (elasticConfiguration) [expand]

POST

acceptable request representations:

  • application/json (elasticConfiguration) [expand]

available response representations:

  • application/json (elasticConfiguration) [expand]

/elasticConfiguration/{configurationId}

resource-wide template parameters
parameter value description

configurationId

long
Methods

GET

available response representations:

  • application/json (elasticConfiguration) [expand]

PUT

acceptable request representations:

  • application/json (elasticConfiguration) [expand]

available response representations:

  • application/json (elasticConfiguration) [expand]

DELETE

available response representations:

/elasticConfiguration/configuration-name/{configurationName}

resource-wide template parameters
parameter value description

configurationName

string
Methods

GET

available response representations:

  • application/json (elasticConfiguration) [expand]

PUT

acceptable request representations:

  • application/json (elasticConfiguration) [expand]

available response representations:

  • application/json (elasticConfiguration) [expand]

DELETE

available response representations:

/elasticConfiguration/image-id/{imageId}?newImageId

resource-wide template parameters
parameter value description

imageId

string
Methods

PUT

request query parameters
parameter value description

newImageId

string

available response representations:

/agent/assignment?executorType&executorId

Methods

GET

request query parameters
parameter value description

executorType

string

executorId

long

available response representations:

  • application/json (dedicatedAgent) [expand]

POST

request query parameters
parameter value description

executorType

string

executorId

long

assignmentType

string

entityId

long

available response representations:

DELETE

request query parameters
parameter value description

executorType

string

executorId

long

assignmentType

string

entityId

long

available response representations:

/agent/assignment/search?executorType&executorId&entityType&searchTerm

Methods

GET

request query parameters
parameter value description

executorType

string

executorId

long

entityType

string

searchTerm

string

available response representations:

  • application/json (searchResults) [expand]

/queue

Lists all the builds waiting in the build queue, adds or removes a build from the build queue. May be used also to resume build on manual stage or rerun failed jobs.

Methods

GET

Provide list of build scheduled for execution and waiting in build queue.

available response representations:

  • 200 - application/xml, application/json (restQueuedBuilds) [expand]

/queue/{projectKey}-{buildKey}?stage&executeAllStages&customRevision

resource-wide template parameters
parameter value description

buildKey

string

projectKey

string
Methods

POST

Fire build execution for specified plan. Effectively, this method adds build to the build queue, so is not guarantied that build would be executed immediately. Depending on currently executed builds and length of build queue, build may be executed when queue would be drained. Additional variables could be passed to this method either as form encoded POST payload or query parameters. PLEASE note: Query parameters are more important - override those stored in form payload. Variables defined in Bamboo as global variables or plan variables MUST be prefixed with bamboo.variable ie. bamboo.variable.myVariable=valueForMyVariable. When global or plan variables would be passed to this method, will override default values for variables.

request query parameters
parameter value description

stage

string

executeAllStages

boolean

customRevision

string

acceptable request representations:

  • application/xml [expand]
  • application/json [expand]
  • application/x-www-form-urlencoded [expand]

available response representations:

  • 415 [expand]
  • 404 [expand]
  • 200 - application/xml, application/json (restQueuedBuild) [expand]
  • 401 [expand]
  • 400 [expand]

/queue/{projectKey}-{buildKey}-{buildNumber : ([0-9]+)}?stage&executeAllStages

resource-wide template parameters
parameter value description

buildNumber

int

build number to resume/rerun

buildKey

string

plan key (only top level plan key, can not be job key)

projectKey

string

project key
Methods

PUT

Continue partially done build. Effectively, this method adds build to the build queue, so is not guarantied that build would be executed immediately. Depending on currently executed builds and length of build queue, build may be executed when queue would be drained. Additional variables could be passed to this method only query parameters (variableName=variableValue). Variables defined in Bamboo as global variables or plan variables MUST be prefixed with bamboo.variable ie. bamboo.variable.myVariable=valueForMyVariable. When global or plan variables would be passed to this method, will override values valid for previous build execution (override).

request query parameters
parameter value description

stage

string

name of the stage that should be executed even if manual stage. Execution will follow to the next manual stage after this or end of plan if no subsequent manual stage

executeAllStages

boolean

enforce executing all stages in a plan, even if defined as manual stages. Execution will follow and include latest stage, unless some stage will fail.

available response representations:

  • 404 [expand]
  • 200 - application/xml, application/json (restQueuedBuild) [expand]
  • 401 [expand]
  • 400 [expand]

/queue/{projectKey}-{buildKey}-{buildNumber}

resource-wide template parameters
parameter value description

buildNumber

int

build number

buildKey

string

plan key - IMPORTANT: as build queue contains only jobs not top level plans, plan key here MUST be a job key as opposite to other methods in this resource.

projectKey

string

project key
Methods

DELETE

Stop build execution, however only if build has not been started yet - so if is waiting in the build queue. If build does not exist in the queue anymore, method has no effect.

available response representations:

  • 204 [expand]
  • 404 [expand]
  • 401 [expand]

/plan/favicon

Methods

/plan/favicon/{planKey}

resource-wide template parameters
parameter value description

planKey

string
Methods

GET

available response representations:

  • application/json (favicon) [expand]

/deploy/version

Methods

/deploy/version/{id}/status

resource-wide template parameters
parameter value description

id

string
Methods

GET

available response representations:

  • application/json (deploymentVersionStatus) [expand]

/deploy/version/{id}/status/{state}

resource-wide template parameters
parameter value description

id

string

state

string
Methods

POST

available response representations:

  • application/json (deploymentVersionStatus) [expand]

/project

Methods

GET

Method used to list all projects defined in Bamboo. Permissions for projects are checked based on Plan permissions (no project level permissions in Bamboo) Projects without any plan visible for user are not listed Should be invoked as /rest/api/latest/project <p/> Possible expand parameters projects - list of projects projects.project - list of projects with project details projects.project.plans - list of project details and plans for project projects.project.plans.plan - list of project details and plans for project with plan details

available response representations:

  • application/xml (projects) [expand]
  • application/json (projects) [expand]

/project/{projectKey}

resource-wide template parameters
parameter value description

projectKey

string
Methods

GET

Method used to retrieve information for project specified as project key Should be invoked as /rest/api/latest/project/PROJECTKEY <p/> Possible expand parameters plans - list of plans for project plans.plan - list of plans with plan details (only plans visible - READ permission for user) plans.plan.actions - list of plans with plan details and actions available for user for plan

available response representations:

  • application/xml (project) [expand]
  • application/json (project) [expand]

/result?expand&favourite&label&issueKey&includeAllStates&continuable&buildstate&start-index&max-results

Provide build results information. Available for anonymous and authenticated users, however proper permissions are enforced

Methods

GET

Provide list of latest build results for top level plans visible for users.

request query parameters
parameter value description

expand

string

expands build result details on request. Possible values are: artifacts, comments, labels, jiraIssues, stages. stages expand is available only for top level plans. It allows to drill down to job results using stages.stage.results.result. All expand parameters should contain results.result prefix.

favourite

boolean

filters build results list to show only results for favourite plans. Works only for authenticated user

label

string

filter by comma separated list of labels

issueKey

string

filter by comma separated list of Jira issue key related to result

includeAllStates

boolean

return all build results including Unknown states

continuable

boolean

filter only results that may be continued (stopped on Manual Stage)

buildstate

boolean

filter results by state, valid values are Unknown, Successful, Failed

start-index

int

start index for results list (zero based)

max-results

int

maximum size for returned list

available response representations:

  • 200 - application/xml, application/json (restResults) [expand]

/result/{projectKey}-{buildKey}-{buildNumber : ([0-9]+)|(latest)}?expand&favourite&start-index&max-results

resource-wide template parameters
parameter value description

buildNumber

string

either the number of the specific build result or 'latest' for the highest build number

buildKey

string

plan key (might be simply planKey or composite planKey-jobKey)

projectKey

string

project key
Methods

GET

Provide build result specified by projectKey-buildKey-buildNumber. Build number may be specified as "latest" for the result with the highest build number.

request query parameters
parameter value description

expand

string

expands build result details on request. Possible values are: changes, metadata, artifacts, comments, labels, jiraIssues, stages, logEntries. stages expand is available only for top level plans. It allows to drill down to job results using stages.stage.results.result. logEntries and testResults are available only for job results

favourite

boolean

filters build results list to show only results for favourite plans. Works only for authenticated user

start-index

int

start index for results list (zero based)

max-results

int

maximum size for returned list

available response representations:

  • 404 [expand]
  • 200 - application/xml, application/json (resultDetails) [expand]
  • 401 [expand]

/result/{projectKey}?expand&favourite&label&issueKey&includeAllStates&continuable&buildstate&start-index&max-results

resource-wide template parameters
parameter value description

projectKey

string

project key to filter plan result list
Methods

GET

Provide list of latest build results for top level plans for specified project. List of results is limited to plans visible for user.

request query parameters
parameter value description

expand

string

expands build result details on request. Possible values are: artifacts, comments, labels, jiraIssues, stages. stages expand is available only for top level plans. It allows to drill down to job results using stages.stage.results.result. All expand parameters should contain results.result prefix.

favourite

boolean

filters build results list to show only results for favourite plans. Works only for authenticated user

label

string

filter by comma separated list of labels

issueKey

string

filter by comma separated list of Jira issue key related to result

includeAllStates

boolean

return all build results including Unknown states

continuable

boolean

filter only results that may be continued (stopped on Manual Stage)

buildstate

boolean

filter results by state, valid values are Unknown, Successful, Failed

start-index

int

start index for results list (zero based)

max-results

int

maximum size for returned list

available response representations:

  • 404 [expand]
  • 200 - application/xml, application/json (restResults) [expand]

/result/byChangeset/{csid}

resource-wide template parameters
parameter value description

csid

string

changeset id related to build result
Methods

GET

Provide list of build results related to changeset id passed as parameter. List of results contains results from all plans related to this changeset.

available response representations:

  • 200 - application/xml, application/json (restResults) [expand]

/result/{projectKey}-{buildKey}?expand&favourite&label&issueKey&includeAllStates&continuable&buildstate&start-index&max-results

resource-wide template parameters
parameter value description

buildKey

string

plan key (might be simply planKey or composite planKey-jobKey)

projectKey

string

project key
Methods

GET

Provide list of build results for specified plan. Plan might be top level plan (projectKey-planKey) or job plan (projectKey-planKey-jobKey).

request query parameters
parameter value description

expand

string

expands build result details on request. Possible values are: artifacts, comments, labels, jiraIssues, stages. stages expand is available only for top level plans. It allows to drill down to job results using stages.stage.results.result. All expand parameters should contain results.result prefix.

favourite

boolean

filters build results list to show only results for favourite plans. Works only for authenticated user

label

string

filter by comma separated list of labels

issueKey

string

filter by comma separated list of Jira issue key related to result

includeAllStates

boolean

return all build results including Unknown states

continuable

boolean

filter only results that may be continued (stopped on Manual Stage)

buildstate

boolean

filter results by state, valid values are Unknown, Successful, Failed

start-index

int

start index for results list (zero based)

max-results

int

maximum size for returned list

available response representations:

  • 404 [expand]
  • 200 - application/xml, application/json (restResults) [expand]
  • 401 [expand]

/result/{projectKey}-{buildKey}/branch/{branchName}?expand&favourite&label&issueKey&includeAllStates&continuable&buildstate&start-index&max-results

resource-wide template parameters
parameter value description

buildKey

string

branchName

string

projectKey

string
Methods

GET

Provide list of build results for specified plan. Plan might be top level plan (projectKey-planKey) or job plan (projectKey-planKey-jobKey).

request query parameters
parameter value description

expand

string

favourite

boolean

label

string

issueKey

string

includeAllStates

boolean

continuable

boolean

buildstate

boolean

start-index

int

max-results

int

available response representations:

  • 404 [expand]
  • 200 - application/xml, application/json (restResults) [expand]
  • 401 [expand]

/result/{projectKey}-{buildKey}/{buildNumber : ([0-9]+)|(latest)}?expand&favourite&start-index&max-results

resource-wide template parameters
parameter value description

buildNumber

string

either the number of the specific build result or 'latest' for the highest build number

buildKey

string

plan key (might be simply planKey or composite planKey-jobKey)

projectKey

string

project key
Methods

GET

Provide build result specified by projectKey-buildKey-buildNumber. Build number may be specified as "latest" for the result with the highest build number.

request query parameters
parameter value description

expand

string

expands build result details on request. Possible values are: changes, metadata, artifacts, comments, labels, jiraIssues, stages, logEntries. stages expand is available only for top level plans. It allows to drill down to job results using stages.stage.results.result. logEntries and testResults are available only for job results

favourite

boolean

filters build results list to show only results for favourite plans. Works only for authenticated user

start-index

int

start index for results list (zero based)

max-results

int

maximum size for returned list

available response representations:

  • 404 [expand]
  • 200 - application/xml, application/json (resultDetails) [expand]
  • 401 [expand]

/result/{projectKey}-{buildKey}-{buildNumber}/comment

resource-wide template parameters
parameter value description

buildNumber

string

build number

buildKey

string

plan key (might be simply planKey or composite planKey-jobKey)

projectKey

string

project key
Methods

GET

Provide list of comments for build result specified by projectKey-buildKey-buildNumber. Build number may be specified as "latest" for the result with the highest build number.

available response representations:

  • 404 [expand]
  • 200 - application/xml, application/json (restCommentList) [expand]
  • 401 [expand]

POST

Adds new comment to build result specified by projectKey-buildKey-buildNumber.

acceptable request representations:

  • application/xml (comment) [expand]
  • application/json (comment) [expand]

/result/{projectKey}-{buildKey}-{buildNumber}/label

resource-wide template parameters
parameter value description

buildNumber

string

either the number of the specific build result or 'latest' for the highest build number

buildKey

string

plan key (might be simply planKey or composite planKey-jobKey)

projectKey

string

project key
Methods

GET

Provide list of labels for build result specified by projectKey-buildKey-buildNumber. Build number may be specified as "latest" for the result with the highest build number.

available response representations:

  • 404 [expand]
  • 200 (restBuildLabelList) [expand]
  • 401 [expand]

POST

Adds new label to build result specified by projectKey-buildKey-buildNumber. Build number may be specified as "latest" for the result with the highest build number.

acceptable request representations:

  • application/xml (label) [expand]
  • application/json (label) [expand]

/result/{projectKey}-{buildKey}-{buildNumber}/label/{labelName}

resource-wide template parameters
parameter value description

buildNumber

string

either the number of the specific build result or 'latest' for the highest build number

buildKey

string

plan key (might be simply planKey or composite planKey-jobKey)

labelName

string

label name to remove from build result

projectKey

string

project key
Methods

DELETE

Removes label from build result specified by projectKey-buildKey-buildNumber. Build number may be specified as "latest" for the result with the highest build number.

/result/status/{projectKey}-{buildKey}-{buildNumber : ([0-9]+)}

resource-wide template parameters
parameter value description

buildNumber

string

buildNumber (numeric value only, 'latest' keyword is not supported for this method)

buildKey

string

plan key (might be simply planKey or composite planKey-jobKey)

projectKey

string

project key
Methods

GET

Provide runtime information for currently executing build result. The key difference to other methods is that method is optimized to provide information available in memory only, so no database calls are made. The information provided is not as wide as for finished results, but the call is optimized for speed.

available response representations:

  • 404 [expand]
  • 200 (restResultStatus) [expand]
  • 401 [expand]

/search

Methods

/search/users?searchTerm&includeAvatars

Methods

GET

A starts-with search of users based on their username, full-name and if allowed email address.

request query parameters
parameter value description

searchTerm

string

Mandatory. The term to search for in users.

includeAvatars

boolean

if true will include avatar urls in the response. If gravatar is not enabled, no urls will be returned

available response representations:

  • 200 - application/xml, application/json (searchResultsList) [expand]

/search/authors?searchTerm&unlinkedOnly

Methods

GET

A starts-with search of authors based on their authorname,

request query parameters
parameter value description

searchTerm

string

Mandatory. The term to search for in authors.

unlinkedOnly

boolean

if true will only include authors which are not currently linked to a user.

available response representations:

  • 200 - application/xml, application/json (searchResultsList) [expand]

/search/plans?searchTerm

Methods

GET

Performs a "starts with" search against full plan name and full plan key. Use "type" argument to filter by plan type by default will return TopLevelPlans

request query parameters
parameter value description

searchTerm

string

to search for. Optional

available response representations:

  • application/xml (searchResults) [expand]
  • application/json (searchResults) [expand]

/search/branches?masterPlanKey&includeMasterBranch&releasedInDeployment&searchTerm

Methods

GET

Performs a "starts with" search against full plan branch name and full plan branch key. Branches are restricted to "masterPlanKey" plan.

request query parameters
parameter value description

masterPlanKey

string

includeMasterBranch

boolean

releasedInDeployment

int

searchTerm

string

available response representations:

  • application/xml (searchResults) [expand]
  • application/json (searchResults) [expand]

/search/projects?searchTerm

Methods

GET

Performs a contains search against project name.

request query parameters
parameter value description

searchTerm

string

to search for. Optional

available response representations:

  • application/xml (searchResults) [expand]
  • application/json (searchResults) [expand]

/search/versions?searchTerm&deploymentProjectId&branchKey&chronologicalOrder

Methods

GET

Performs a contains search against a version name.

request query parameters
parameter value description

searchTerm

string

deploymentProjectId

long

branchKey

string

chronologicalOrder

boolean

available response representations:

  • application/xml (searchResults) [expand]
  • application/json (searchResults) [expand]

/deploy/projectVersioning

Methods

/deploy/projectVersioning/{id}/variables?includePasswords

resource-wide template parameters
parameter value description

id

long
Methods

GET

request query parameters
parameter value description

includePasswords

boolean

available response representations:

  • application/json (versionVariables) [expand]

/deploy/projectVersioning/{id}/namingPreview?nextVersionName&incrementNumbers&incrementableVariables

resource-wide template parameters
parameter value description

id

long
Methods

GET

request query parameters
parameter value description

nextVersionName

string

incrementNumbers

boolean

incrementableVariables

string

available response representations:

  • application/json (restNamingPreview) [expand]

/deploy/projectVersioning/{id}/nextVersion?resultKey

resource-wide template parameters
parameter value description

id

long
Methods

GET

request query parameters
parameter value description

resultKey

string

available response representations:

  • application/json (restNamingPreview) [expand]

/deploy/projectVersioning/{id}/parseVariables?nextVersionName

resource-wide template parameters
parameter value description

id

long
Methods

GET

request query parameters
parameter value description

nextVersionName

string

available response representations:

/server

Methods

GET

available response representations:

/server/pause

Methods

POST

Pauses the server

available response representations:

/server/prepareForRestart

Methods

PUT

Prepare server for restarting: suspend change detection, stop indexing, stop ec2 instance ordering etc

available response representations:

/server/resume

Methods

POST

Resumes the server

available response representations:

/deploy/result

Methods

/deploy/result/{deploymentResultId}?includeLogs

resource-wide template parameters
parameter value description

deploymentResultId

long
Methods

GET

request query parameters
parameter value description

includeLogs

boolean

available response representations:

  • application/json (deploymentResult) [expand]

/reindex?indexer

REST resource for starting/stopping/querying indexing.

Methods

POST

Kicks off a reindex. Requires system admin permissions to perform this reindex.

request query parameters
parameter value description

indexer

string

available response representations:

  • 202 - application/json [expand]

GET

Returns status of the current indexing operation. reindexInProgress - reindex is currently performed in background reindexPending - reindex is required (i.e. it failed before or some upgrade task asked for it)

available response representations:

  • 200 - application/json [expand]
View cookie preferences