Bamboo REST resources

Available:

Bamboo 2.3 introduced the REST APIs.

Changed:

In Bamboo 3.0 the results resource replaced the build resource. Expand parameters also changed from builds.build to results.result.

The Bamboo REST APIs allow you to address the Bamboo data entities as ‘resources’. This means that they are identified by URIs and operated on by HTTP requests, such as GET. Whenever you GET one of these resources, you receive a representation encoded using XML or JSON.

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

The REST API usage guide describes common factors in the APIs, including the full structure of the URIs, API versions, etc. Below are details of the resources made available by the APIs.

General Information

You can always view the root level resources for a particular version of a Bamboo REST API by navigating to the root URI. e.g.

1
http://myhost.com:8085/rest/api/latest/

The response of a REST call will always contains information about size of whole collection (size attribute) as well as the start-index and max-result.

The number of resources in returned lists is limited to 25, unless you specify max-result.

Project Service

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

URI

/project

Description

Lists all the projects set up on the Bamboo server.

URI Parameters
  • ?expand=projects or no parameter – List projects with projects list expanded and links to projects available.
  • ?expand=projects.project – List projects with projects list expanded and project details visible.
  • ?expand=projects.project.plans – List of projects and plans belonging to the project with plans expanded and links to plans available.
  • ?expand=projects.project.plans.plan – List of projects and plans belonging to the project with plans expanded and plan details visible.
  • ?expand=projects.project.plans.plan.actions – List of projects and plans belonging to the project with plans expanded, and plan details and actions visible.
  • ?favourite&expand=projects.project.plans – List of projects and favourite plans belonging to the project with plans expanded and links to plans available. Plans which are not favourites will not be returned.
  • ?favourite&expand=projects.project.plans.plan – List of projects and favourite plans belonging to the project with plans expanded and plan details visible. Plans which are not favourites will not be returned.
  • ?favourite&expand=projects.project.plans.plan.actions – List of projects and favourite plans belonging to the project with plans expanded, and plan details and actions visible. Plans which are not favourites will not be returned.
  • ?cloverEnabled&expand=projects.project.plans – List of projects and Clover-enabled plans 1 belonging to the project with plans expanded and links to plans available. Plans which are not favourites will not be returned.
  • ?cloverEnabled&expand=projects.project.plans.plan – List of projects and Clover-enabled plans 1 belonging to the project with plans expanded and plan details visible. Plans which are not favourites will not be returned.
  • ?cloverEnabled&expand=projects.project.plans.plan.actions – List of projects and Clover-enabled plans 1 belonging to the project with plans expanded, and plan details and actions visible. Plans which are not favourites will not be returned.
     
    1 A plan is Clover-enabled if Clover output will be produced by the build (See Configuring a builder taskfor a plan).

HTTP Methods
  • GET – Returns a list of projects.

Example of response XML:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <projects expand="projects">
<link rel="self" href="http://myhost:8085/rest/api/latest/project" />
- <projects expand="project" size="2" max-result="2" start-index="0">
- <project name="MyProject1" key="MYPROJ1">
<link rel="self" href="http://myhost:8085/rest/api/latest/project/MYPROJ1" />
</project>
- <project name="MyProject2" key="MYPROJ2">
<link rel="self" href="http://myhost:8085/rest/api/latest/project/MYPROJ2" />
</project>
</projects>
</projects>

Elements in the response:

Element

Attributes

projects/project
  • name -- Name of the project
  • key -- Project key

projects/project/link
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the project

Example of response JSON:

1
2
3
4
5
{"expand":"projects","link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/project"},
"projects":{"expand":"project","size":2,"max-result":2,"start-index":0,"project":[
{"name":"MyProject1","key":"MYPROJ1","link":{"rel":"self","href":"http://panda:8085/rest/api/latest/project/MYPROJ1"}},
{"name":"MyProject2","key":"MYPROJ2","link":{"rel":"self","href":"http://panda:8085/rest/api/latest/project/MYPROJ2"}}
]}}

Plan Service

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

URI

/plan

Description

Lists all the plans set up on the Bamboo server.

URI Parameters
  • ?expand=plans or no parameter – List all plans for all projects with list expanded (but no plan details).
  • ?expand=plans.plan – List all plans for all projects with list expanded and plan details visible.
  • ?expand=plans.plan.actions – List all plans for all projects with list expanded and plan details and plan actions visible.
  • ?favourite&expand=plans.plan – List all favourite plans for all projects with list expanded and plan details visible. Plans which are not favourites will not be returned.
  • ?favourite&expand=plans.plan.actions – List all favourite plans for all projects with list expanded and plan details and plan actions visible. Plans which are not favourites will not be returned.
  • ?cloverEnabled&expand=plans.plan – List all Clover-enabled plans 1 plans for all projects with list expanded and plan details visible. Plans which are not favourites will not be returned.
  • ?cloverEnabled&expand=plans.plan.actions – List all Clover-enabled plans 1 plans for all projects with list expanded and plan details and plan actions visible. Plans which are not favourites will not be returned.
     
    1 A plan is Clover-enabled if Clover output will be produced by the build (See Configuring a builder taskfor a plan).

HTTP Methods
  • GET – Returns a list of plans.

Example of response XML:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <plans expand="plans">
<link rel="self" href="http://myhost:8085/rest/api/latest/plan"/>
- <plans expand="plan" size="3" max-result="3" start-index="0">
- <plan enabled="true" plan name="My Plan 1" key="MYPLAN1">
<link rel="self" href="http://myhost:8085/rest/api/latest/plan/MYPLAN1"/>
</plan>
- <plan enabled="true" name="My Plan 2" key="MYPLAN2">
<link rel="self" href="http://myhost:8085/rest/api/latest/plan/MYPLAN2"/>
</plan>
- <plan enabled="true" name="My Plan 3" key="MYPLAN3">
<link rel="self" href="http://myhost:8085/rest/api/latest/plan/MYPLAN3"/>
</plan>
</plans>
</plans>

Elements in the response:

Element

Attributes

plans/plan
  • name -- Name of the plan
  • key -- Plan key

plans/plan/link
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the plan

Example of response JSON:

1
2
3
4
5
6
{"expand":"plans","link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/plan"},
"plans":{"expand":"plan","size":2,"max-result":2,"start-index":0,"plan":[
{"name":"My Plan 1","key":"MYPLAN1","link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/plan/MYPLAN1"}},
{"name":"My Plan 2","key":"MYPLAN2","link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/plan/MYPLAN2"}}
{"name":"My Plan 3","key":"MYPLAN3","link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/plan/MYPLAN3"}}
]}}

Build Service – All Builds

Changed:

In Bamboo 3.0 the results resource replaced the build resource. Expand parameters also changed from builds.build to results.result.

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

URI

/result

Description

Lists the latest builds for all plans on the Bamboo server.

URI Parameters
  • ?expand=results or no parameter – Lists the latest build for each of the plans on the Bamboo server, in descending order (by completion time).
  • ?expand=results.result – Lists the latest build for each of the plans on the Bamboo server with build details expanded, in descending order (by completion time) (Warning: This can be a very resource-intensive operation. You may wish to consider limiting the number of builds returned).

  • ?expand=results[0:N].result – Lists the last Nbuilds for the plans on the Bamboo server with build result details expanded, in descending order (by completion time).

    Modifying the build array parameters

    You can modify the build array parameters (i.e. [0:N]) to return different sets of results.
    * Use [0] to return the latest build result.
    * Use negative indexes to return the last entries in build list, e.g. [-5:-1] returns last five builds in list
    * Use open ended arrays to return all results from start or end of builds list, e.g. [1:] returns all builds from first to the list limit, [:5] returns first 6 entries in build list.

  • ?favourite – List the latest builds for all favourite plans on the Bamboo server.
  • ?label=labelname – List the latest builds which have a build result labelled with a particular label(s). labelname can be the name of a single label (e.g. deploy_failed) or a comma-separated list of label names (e.g. {deploy_failed,deploy_successful)
  • ?issueKey=issuekey – List the latest builds which have a build result related to one or many JIRA issues. issuekey can be the key of a single JIRA issue (e.g. BAM-1111) or a comma-separated list of label names (e.g. {BAM-1111,BAM-1112,BAM-1113)
  • ?cloverEnabled – List the latest builds all Clover-enabled plans 1 plans on the Bamboo server.
    1 A plan is Clover-enabled if Clover output will be produced by the build (See Configuring a builder task for a plan).
  • ?expand=results.result.artifacts – Lists the artifacts produced by each of the latest builds for all plans on the Bamboo server.
  • ?expand=results.result.labels – Lists the labels associated with each of the latest builds for all plans on the Bamboo server.
  • ?expand=results.result.comments – Lists the comments associated with each of the latest builds for all plans on the Bamboo server.
  • ?expand=results.result.jiraIssues – Lists the JIRA issues associated with each of the latest builds for all plans on the Bamboo server.

Example of response XML:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <results expand="results">
<link rel="self" href="http://myhost:8085/rest/api/latest/result"/>
- <results expand="result" size="5" max-result="5" start-index="0">
- <result number="2" state="Successful" key="MYPLAN1-2">
<link rel="self" href="http://myhost:8085/rest/api/latest/result/MYPROJ1-MYPLAN1-2"/>
</result>
<result number="5" state="Successful" key="MYPLAN2-5">
<link rel="self" href="http://myhost:8085/rest/api/latest/result/MYPROJ1-MYPLAN2-5"/>
</result>
<result number="4" state="Successful" key="MYPLAN3-4">
<link rel="self" href="http://myhost:8085/rest/api/latest/result/MYPROJ1-MYPLAN3-4"/>
</result>
<result number="5" state="Successful" key="MYPLAN4-5">
<link rel="self" href="http://myhost:8085/rest/api/latest/result/MYPROJ2-MYPLAN4-5"/>
</result>
<result number="5" state="Successful" key="MYPLAN5-5">
<link rel="self" href="http://myhost:8085/rest/api/latest/result/MYPROJ3-MYPLAN5-5"/>
</result>
</results>
</results>

Elements in the response:

Element

Attributes

results/result
  • number -- Build result number
  • state -- State of the build (e.g. Successful, Failed)
  • key -- Key of the build result

results/result/link
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the build result

result/buildStartedTime

Description: Start time of build

result/buildCompletedTime

Description: Finish time of build

result/buildDurationInSeconds

Description: Build duration in seconds

result/buildDurationDescription

Description: Description of build duration (conversion of seconds to more usable units of time)

result/buildRelativeTime

Description: Time when build was run (relative to current time)

result/queueStartedTime

Description: Time when build was queued

result/queueTimeInSeconds

Description: How long build was queued

result/vcsUpdateStartedTime

Description: Time when VCS update occurred

result/vcsUpdateInSeconds

Description: How long VCS took to complete

result/buildTestSummary

Description: Summary of test results

result/successfulTestCount

Description: Number of successful tests in build

result/failedTestCount

Description: Number of failed tests in build

result/buildReason

Description: Reason for build

results/result/artifacts/artifact/name

Description: Name of the build artifact

results/result/artifacts/artifact/link
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the build artifact

results/result/labels/label/name

Description: Name of the label

results/result/comments/comment
  • author -- Author of the comment

results/result/comments/comment/content
  • author -- Author of the comment

results/result/comments/comment/creationDate

Description: Date that comment was created

results/result/comments/comment/modificationDate

Description: Date that comment was last updated

results/result/jiraIssues/issue
  • key -- Key of the JIRA issue

results/result/jiraIssues/issue/url
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the JIRA issue

Example of response JSON:

1
2
3
4
5
6
7
8
{"expand":"results","link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/result"},
"builds":{"expand":"result","size":5,"max-result":5,"start-index":0,"result":[
{"number":,"state":"Successful","key":"MYPROJ1-MYPLAN1","link":{"rel":"self","href":"http://panda:8085/rest/api/latest/result/MYPROJ1-MYPLAN1-2"}},
{"number":,"state":"Successful","key":"MYPROJ1-MYPLAN2","link":{"rel":"self","href":"http://panda:8085/rest/api/latest/result/MYPROJ1-MYPLAN2-5"}},
{"number":,"state":"Successful","key":"MYPROJ1-MYPLAN3","link":{"rel":"self","href":"http://panda:8085/rest/api/latest/result/MYPROJ1-MYPLAN3-4"}},
{"number":,"state":"Successful","key":"MYPROJ2-MYPLAN4","link":{"rel":"self","href":"http://panda:8085/rest/api/latest/result/MYPROJ2-MYPLAN4-5"}},
{"number":,"state":"Successful","key":"MYPROJ3-MYPLAN5","link":{"rel":"self","href":"http://panda:8085/rest/api/latest/result/MYPROJ3-MYPLAN5-5"}},
]}}

Build Service – Specific Project

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

URI

/result/PROJECTKEY
(where PROJECTKEY is the key of the desired project, e.g. MYPROJ1)

Description

Lists the latest builds for all plans for a specific project on the Bamboo server.

URI Parameters
  • ?expand=results or no parameter – Lists the latest builds for each of the plans of a project on the Bamboo server, in descending order (by completion time).
  • ?expand=results.result – Lists the latest builds for each of the plans of a project with build details expanded, in descending order (by completion time) (Warning: This can be a very resource-intensive operation. You may wish to consider limiting the number of build results returned).

  • ?expand=results[0:N].result – Lists the last Nbuilds for the plans of the project with build result details expanded, in descending order (by completion time).

    Modifying the build array parameters

    You can modify the build array parameters (i.e. [0:N]) to return different sets of results.
    * Use [0] to return the latest build result.
    * Use negative indexes to return the last entries in build list, e.g. [-5:-1] returns last five builds in list
    * Use open ended arrays to return all results from start or end of builds list, e.g. [1:] returns all builds from first to the list limit, [:5] returns first 6 entries in build list.

  • ?favourite – List the latest builds for all favourite plans for a specific project on the Bamboo server.
  • ?label=labelname – List the latest builds for a specific project, which have a build result labelled with a particular label(s). labelname can be the name of a single label (e.g. deploy_failed) or a comma-separated list of label names (e.g. {deploy_failed,deploy_successful)
  • ?issueKey=issuekey – List the latest builds for a specific project, which have a build result related to one or many JIRA issues. issuekey can be the key of a single JIRA issue (e.g. BAM-1111) or a comma-separated list of label names (e.g. {BAM-1111,BAM-1112,BAM-1113)
  • ?cloverEnabled – List the latest builds for a specific project, all Clover-enabled plans 1 plans on the Bamboo server.
    1 A plan is Clover-enabled if Clover output will be produced by the build (See Configuring a builder task for a plan).
  • ?expand=results.result.artifacts – Lists the artifacts produced by each of the latest builds for all plans for a specific project.
  • ?expand=results.result.labels – Lists the labels associated with each of the latest builds for all plans for a specific project.
  • ?expand=results.result.comments – Lists the comments associated with each of the latest builds for all plans for a specific project.
  • ?expand=results.result.jiraIssues – Lists the JIRA issues associated with each of the latest builds for all plans for a specific project.

Example of response XML:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <results expand="results">
<link rel="self" href="http://myhost:8085/rest/api/latest/result"/>
- <results expand="result" size="3" max-result="3" start-index="0">
- <result number="2" state="Successful" key="MYPROJ1-MYPLAN1-2">
<link rel="self" href="http://myhost:8085/rest/api/latest/result/MYPROJ1-MYPLAN1-2"/>
</result>
<result number="5" state="Successful" key="MYPROJ1-MYPLAN2-5">
<link rel="self" href="http://myhost:8085/rest/api/latest/result/MYPROJ1-MYPLAN2-5"/>
</result>
<result number="4" state="Successful" key="MYPROJ1-MYPLAN3-4">
<link rel="self" href="http://myhost:8085/rest/api/latest/result/MYPROJ1-MYPLAN3-4"/>
</result>
</results>
</results>

Elements in the response:

Element

Attributes

results/result
  • number -- Build number
  • state -- State of the build (e.g. Successful, Failed)
  • key -- Key of the build result

results/result/link
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the build result

result/buildStartedTime

Description: Start time of build

result/buildCompletedTime

Description: Finish time of build

result/buildDurationInSeconds

Description: Build duration in seconds

result/buildDurationDescription

Description: Description of build duration (conversion of seconds to more usable units of time)

result/buildRelativeTime

Description: Time when build was run (relative to current time)

result/queueStartedTime

Description: Time when build was queued

result/queueTimeInSeconds

Description: How long build was queued

result/vcsUpdateStartedTime

Description: Time when VCS update occurred

result/vcsUpdateInSeconds

Description: How long VCS took to complete

result/buildTestSummary

Description: Summary of test results

result/successfulTestCount

Description: Number of successful tests in build

result/failedTestCount

Description: Number of failed tests in build

result/buildReason

Description: Reason for build

results/build/artifacts/artifact/name

Description: Name of the build artifact

results/build/artifacts/artifact/link
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the build artifact

results/result/labels/label/name

Description: Name of the label

results/result/comments/comment
  • author -- Author of the comment

results/result/comments/comment/content
  • author -- Author of the comment

results/result/comments/comment/creationDate

Description: Date that comment was created

results/result/comments/comment/modificationDate

Description: Date that comment was last updated

results/result/jiraIssues/issue
  • key -- Key of the JIRA issue

results/result/jiraIssues/issue/url
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the JIRA issue

Example of response JSON:

1
2
3
4
5
6
{"expand":"results","link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/result"},
"results":{"expand":"result","size":3,"max-result":3,"start-index":0,"result":[
{"number":,"state":"Successful","key":"MYPROJ1-MYPLAN1","link":{"rel":"self","href":"http://panda:8085/rest/api/latest/result/MYPROJ1-MYPLAN1-2"}},
{"number":,"state":"Successful","key":"MYPROJ1-MYPLAN2","link":{"rel":"self","href":"http://panda:8085/rest/api/latest/result/MYPROJ1-MYPLAN2-5"}},
{"number":,"state":"Successful","key":"MYPROJ1-MYPLAN3","link":{"rel":"self","href":"http://panda:8085/rest/api/latest/result/MYPROJ1-MYPLAN3-4"}},
]}}

Build Service – Specific Plan

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

URI

result/PROJECTKEY-PLANKEY
(where PROJECTKEY-PLANKEY is the key of the desired build plan of a project, e.g. MYPROJ1-MYPLAN1)

Description

Provides information about builds executed for a build plan from latest to the first build

URI Parameters
  • ?expand=results or no parameter – List all build results for the build plan (build details not visible).
  • ?expand=results.result – List all build results for the build plan with build details expanded, in descending order. (Warning: This is a very resource-intensive operation. You should consider limiting the number of builds returned).

  • ?expand=results[0:N].result – List the last Nbuild results for the build plan with build details expanded, in descending order.

    Modifying the build array parameters

    You can modify the build array parameters (i.e. [0:N]) to return different sets of results.
    * Use [0] to return the latest build result.
    * Use negative indexes to return the last entries in build list, e.g. [-5:-1] returns last five builds in list
    * Use open ended arrays to return all results from start or end of builds list, e.g. [1:] returns all builds from first to the list limit, [:5] returns first 6 entries in build list.

  • ?expand=results.result.artifacts – List all build results for the build plan with build details expanded and artifacts displayed, in descending order. (Warning: This is a very resource-intensive operation. You should consider limiting the number of builds returned).
  • ?expand=plan – Displays the build plan information (expanded), including a summary of build results information.
  • ?expand=plan.actions – Displays the build plan information (expanded), including a summary of build results information and available actions.
  • ?expand=results.result.artifacts – Lists the artifacts produced by each of the latest builds for the specified plan.
  • ?expand=results.result.labels – Lists the labels associated with each of the latest builds for the specified plan.
  • ?expand=results.result.comments – Lists the comments associated with each of the latest builds for the specified plan.
  • ?expand=results.result.jiraIssues – Lists the JIRA issues associated with each of the latest builds for the specified plan.

HTTP Methods
  • GET – Returns a list of plans.

Example of response XML:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <results expand="results">
<link rel="self" href="http://myhost:8085/rest/api/latest/result"/>
- <results expand="result" size="2" max-result="2" start-index="0">
- <result number="1" state="Successful" key="MYPROJ1-MYPLAN6-1">
<link rel="self" href="http://myhost:8085/rest/api/latest/result/MYPROJ1-MYPLAN6-1"/>
</result>
<result number="2" state="Successful" key="MYPROJ1-MYPLAN6-2">
<link rel="self" href="http://myhost:8085/rest/api/latest/result/MYPROJ1-MYPLAN6-2"/>
</result>
</results>
</results>

Elements in the response:

Element

Attributes

results/result
  • number -- Build number
  • state -- State of the build (e.g. Successful, Failed)
  • key -- Key of the build result

results/result/link
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the build result

result/buildStartedTime

Description: Start time of build

result/buildCompletedTime

Description: Finish time of build

result/buildDurationInSeconds

Description: Build duration in seconds

result/buildDurationDescription

Description: Description of build duration (conversion of seconds to more usable units of time)

result/buildRelativeTime

Description: Time when build was run (relative to current time)

result/queueStartedTime

Description: Time when build was queued

result/queueTimeInSeconds

Description: How long build was queued

result/vcsUpdateStartedTime

Description: Time when VCS update occurred

result/vcsUpdateInSeconds

Description: How long VCS took to complete

result/buildTestSummary

Description: Summary of test results

result/successfulTestCount

Description: Number of successful tests in build

result/failedTestCount

Description: Number of failed tests in build

result/buildReason

Description: Reason for build

results/result/artifacts/artifact/name

Description: Name of the build artifact

results/result/artifacts/artifact/link
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the build artifact

results/result/labels/label/name

Description: Name of the label

results/result/comments/comment
  • author -- Author of the comment

results/result/comments/comment/content
  • author -- Author of the comment

results/result/comments/comment/creationDate

Description: Date that comment was created

results/result/comments/comment/modificationDate

Description: Date that comment was last updated

results/result/jiraIssues/issue
  • key -- Key of the JIRA issue

results/result/jiraIssues/issue/url
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the JIRA issue

Example of response JSON:

1
2
3
4
5
{"expand":"results","link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/result"},
"results":{"expand":"result","size":2,"max-result":2,"start-index":0,"result":[
{"number":,"state":"Successful","key":"MYPROJ1-MYPLAN6","link":{"rel":"self","href":"http://panda:8085/rest/api/latest/result/MYPROJ1-MYPLAN6-1"}},
{"number":,"state":"Successful","key":"MYPROJ1-MYPLAN6","link":{"rel":"self","href":"http://panda:8085/rest/api/latest/result/MYPROJ1-MYPLAN6-1"}},
]}}

Build Service – Specific Build Result

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

URI

/result/PROJECTKEY-PLANKEY/BUILDNUMBER
(where PROJECTKEY-PLANKEY is the key of the desired build plan of a project, e.g. MYPROJ1-MYPLAN1, and BUILDNUMBER is the number of the build, e.g. 1, latest, etc)

result/PROJECTKEY-PLANKEY-JOBKEY/BUILDNUMBER(where PROJECTKEY-PLANKEY-JOBKEY is the key of the desired build job, e.g. MYPROJ1-MYPLAN1-JOB1, and BUILDNUMBER is the number of the build, e.g. 1, latest, etc) 

Description

Provides information about a single build executed for a build plan (build result information only)

URI Parameters
  • no parameter – Displays the latest build result for the plan.
  • ?expand=artifacts – Displays the latest build result for the plan and an expanded list of artifacts.
  • ?expand=changes – Displays the latest build result for the plan and list of changes for build.
  • ?expand=results.result.artifacts – Lists the artifacts for the specified build result.
  • ?expand=results.result.labels – Lists the labels for the specified build result.
  • ?expand=results.result.comments – Lists the comments for the specified build result.
  • ?expand=results.result.jiraIssues – Lists the JIRA issues for the specified build result.
  • ?expand=changes – Lists the changesets for the specified build result.
  • ?expand=changes.change – Lists the changesets (changeset details expanded) for the specified build result.
  • ?expand=changes.change.files – Lists the changesets (changeset details and file details expanded) for the specified build result.
  • ?expand=testResults – Lists the test results for the specified build result. Note: you need JOB result to expand testResults.
  • ?expand=testResults.failedTests – Lists the failed test results for the specified build result. Note: you need JOB result to expand testResults.
  • ?expand=testResults.failedTests.testResult – Lists the failed test results (test result details expanded) for the specified build result. Note: you need JOB result to expand testResults.
  • ?expand=testResults.failedTests.testResult.errors – Lists the failed tests (test result details and errors expanded) for the specified build result. Note: you need JOB result to expand testResults.
  • ?expand=metadata – Lists the metadata for the specified build result.

HTTP Methods
  • GET – Returns the latest build result.

Example of response XML:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <result number="5157" state="Successful" key="MYPLAN1-5157" expand="artifacts">
<failedTestCount>0</failedTestCount>
<successfulTestCount>1617</successfulTestCount>
<buildStartedTime>2009-06-15T14:56:06.821+1000</buildStartedTime>
<buildCompletedTime>2009-06-15T15:14:10.994+1000</buildCompletedTime>
<buildDurationInSeconds>1084.0</buildDurationInSeconds>
<buildDurationDescription>18 minutes</buildDurationDescription>
<buildRelativeTime>1 hour ago</buildRelativeTime>
<buildTestSummary>1617 passed</buildTestSummary>
<buildReason><a href="http://myhost:8085/browse/MYPLAN1-5157/commit">Updated by Austin Powers</a></buildReason>
<queueStartedTime>2009-06-15T14:53:54.499+1000</queueStartedTime>
<queueTimeInSeconds>1.0</queueTimeInSeconds>
<vcsUpdateStartedTime>2009-06-15T14:53:55.546+1000</vcsUpdateStartedTime>
<vcsUpdateInSeconds>131.0</vcsUpdateInSeconds>
<artifacts size="1" max-result="1" start-index="0" />
<link rel="self" href="http://myhost:8085/rest/api/latest/build/MYPLAN1-5157" />
</result>

Elements in the response:

Element

Attributes

result
  • number -- number of the build result
  • state -- state of the build result
  • key -- key for the build result
  • expand -- elements to expand in response

link
  • rel -- relationship between link and element (defaults to "self")
  • href -- URL for the build result

result/buildStartedTime

Description: Start time of build

result/buildCompletedTime

Description: Finish time of build

result/buildDurationInSeconds

Description: Build duration in seconds

result/buildDurationDescription

Description: Description of build duration (conversion of seconds to more usable units of time)

result/buildRelativeTime

Description: Time when build was run (relative to current time)

result/queueStartedTime

Description: Time when build was queued

result/queueTimeInSeconds

Description: How long build was queued

result/vcsUpdateStartedTime

Description: Time when VCS update occurred

result/vcsUpdateInSeconds

Description: How long VCS took to complete

result/buildTestSummary

Description: Summary of test results

result/successfulTestCount

Description: Number of successful tests in build

result/failedTestCount

Description: Number of failed tests in build

result/buildReason

Description: Reason for build

results/result/artifacts/artifact/name

Description: Name of the build artifact

results/result/artifacts/artifact/link
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the build artifact

results/result/labels/label/name

Description: Name of the label

results/result/comments/comment
  • author -- Author of the comment

results/result/comments/comment/content
  • author -- Author of the comment

results/result/comments/comment/creationDate

Description: Date that comment was created

results/result/comments/comment/modificationDate

Description: Date that comment was last updated

results/result/jiraIssues/issue
  • key -- Key of the JIRA issue

results/result/jiraIssues/issue/url
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the JIRA issue

results/result/changes/change
  • changesetid -- Id of the changeset
  • author -- Author of the changeset

results/result/changes/change/comment

Description: Comment associated with the changeset

results/result/changes/change/date

Description: Date of the changeset

results/result/changes/change/files/file/name

Description: Name of the file associated with the changeset

results/result/changes/change/files/file/revision

Description: Revision of the file associated with the changeset

results/result/testResults/successful
  • size -- Number of successful tests

results/result/testResults/failed
  • size -- Number of failed tests

results/result/testResults/failed/testResult
  • status -- status of test, i.e. "failed"
  • methodName -- Method associated with failed test
  • className -- Class associated with failed test

results/result/testResults/failed/testResult/duration

Description: Duration of test

results/result/testResults/failed/testResult/ durationInSeconds

Description: Duration of test in seconds

results/result/testResults/failed/testResult/errors
  • size -- Number of errors in test

results/result/testResults/failed/testResult/errors/ error/message

Description: Error message for error in failed test.

Example of response JSON:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{"number":5157,"state":"Successful","key":"MYPLAN1-5157","expand":"artifacts",
"failedTestCount":0,
"successfulTestCount":1617,
"buildStartedTime":"2009-06-15T14:56:06.821+1000",
"buildCompletedTime":"2009-06-15T15:14:10.994+1000",
"buildDurationInSeconds":1084.0,
"buildDurationDescription":"18 minutes",
"buildRelativeTime":"2 hours ago",
"buildTestSummary":"1617 passed",
"buildReason":"<a href=\"http://myhost:8085/browse/BAM-MAIN-5157/commit\">Updated by Austin Powers</a>",
"queueStartedTime":"2009-06-15T14:53:54.499+1000",
"queueTimeInSeconds":1.0,
"vcsUpdateStartedTime":"2009-06-15T14:53:55.546+1000",
"vcsUpdateInSeconds":131.0,
"artifacts":{"size":1,"max-result":1,"start-index":0},
"link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/result/MYPLAN1-5157"}}

Chart Service

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

URI

/chart

Description

Returns detailed information on a specific chart, or returns the list of reports set up on the Bamboo server.

URI Parameters
  • reportKey – report class as returned by /chart/reports resource in key tag
  • buildKeys – comma-separated list of build keys (PROJECTKEY-PLANKEY) as returned by /chart/reports resource
  • groupByPeriod – period to group results by in the report chart. Valid values = AUTO, DAY, WEEK, MONTH
  • dateFilter (optional) – date period to filter results by in the report chart. Valid values = LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, ALL, RANGE (requires a valid dateFrom and dateTo as described below)
  • dateFrom (optional) – start date for report chart as dd/MM/yyyy, (e.g. 15/6/2009), mandatory if dateFilter=RANGE
  • dateTo (optional) – end date for report chart as dd/MM/yyyy, (e.g. 15/6/2009), mandatory if dateFilter=RANGE
  • width (optional) – width of the chart in pixels
  • height (optional) – height of the chart in pixels

HTTP Methods
  • GET – Returns a list of reports.

Example of response XML (list all available reports):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<chart>
<location>jfreechart-onetime-3627918147160569458.png</location>
<imageMapName>OZ6yx_map</imageMapName>
<imageMap>
<map id="OZ6yx_map" name="OZ6yx_map">
<area shape="poly" coords="373,45,379,45,379,51,373,51,373,45,373,45"
title="INT-TST on average took 38 seconds for June 2009" alt="" nohref="nohref"/>
<area shape="poly" coords="328,76,334,76,334,82,328,82,328,76,328,76"
title="INT-TST on average took 36 seconds for May 2009" alt="" nohref="nohref"/>
<area shape="poly" coords="284,121,290,121,290,127,284,127,284,121,284,121"
title="INT-TST on average took 32 seconds for April 2009" alt="" nohref="nohref"/>
<area shape="poly" coords="239,242,245,242,245,248,239,248,239,242,239,242"
title="INT-TST on average took 23 seconds for March 2009" alt="" nohref="nohref"/>
<area shape="poly" coords="199,190,205,190,205,196,199,196,199,190,199,190"
title="INT-TST on average took 27 seconds for February 2009" alt="" nohref="nohref"/>
<area shape="poly" coords="154,14,160,14,160,20,154,20,154,14,154,14"
title="INT-TST on average took 40 seconds for January 2009" alt="" nohref="nohref"/>
<area shape="poly" coords="109,204,115,204,115,210,109,210,109,204,109,204"
title="INT-TST on average took 26 seconds for December 2008" alt="" nohref="nohref"/>
<area shape="poly" coords="65,210,71,210,71,216,65,216,65,210,65,210"
title="INT-TST on average took 26 seconds for November 2008" alt="" nohref="nohref"/>
<area shape="poly" coords="379,58,378,60,376,61,374,60,373,58,374,56,376,55,378,56,379,58,379,58"
title="ACC-TST on average took 37 seconds for June 2009" alt="" nohref="nohref"/>
<area shape="poly" coords="334,107,333,109,331,110,329,109,328,107,329,105,331,104,333,105,334,107,334,107"
title="ACC-TST on average took 33 seconds for May 2009" alt="" nohref="nohref"/>
<area shape="poly" coords="290,138,290,140,287,141,285,140,284,138,285,136,287,135,290,136,290,138,290,138"
title="ACC-TST on average took 31 seconds for April 2009" alt="" nohref="nohref"/>
<area shape="poly" coords="245,155,245,157,242,158,240,157,239,155,240,153,242,152,245,153,245,155,245,155"
title="ACC-TST on average took 30 seconds for March 2009" alt="" nohref="nohref"/>
<area shape="poly" coords="205,182,204,184,202,185,200,184,199,182,200,180,202,179,204,180,205,182,205,182"
title="ACC-TST on average took 28 seconds for February 2009" alt="" nohref="nohref"/>
<area shape="poly" coords="160,186,159,188,157,189,154,188,154,186,154,184,157,183,159,184,160,186,160,186"
title="ACC-TST on average took 28 seconds for January 2009" alt="" nohref="nohref"/>
<area shape="poly" coords="115,212,114,214,112,215,109,214,109,212,109,210,112,209,114,210,115,212,115,212"
title="ACC-TST on average took 26 seconds for December 2008" alt="" nohref="nohref"/>
<area shape="poly" coords="71,195,70,197,68,198,66,197,65,195,66,193,68,192,70,193,71,195,71,195"
title="ACC-TST on average took 27 seconds for November 2008" alt="" nohref="nohref"/>
</map>
</imageMap>
<width>400</width>
<height>320</height>
</chart>

Elements in the response:

Element

Attributes

location

Description: URL for the chart image

imageMapName

Description: Name of the imagemap

area
  • shape -- shape of area element, defaults to "poly"
  • coords -- co-ordinates of the area
  • title -- caption of the area
  • alt -- text displayed if area does not render
  • nohref -- defaults to "nohref"

width

Description: width of the chart image in pixels

height

Description: height of the chart image in pixels

Report Service

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

URI

/chart/reports

Description

Returns the list of reports set up on the Bamboo server.

URI Parameters
  • no parameter – List all available reports
  • ?expand=reports – List all available reports with report details expanded.

HTTP Methods
  • GET – Returns a list of reports.

Example of response XML (list all available reports):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <reports expand="reports">
<link rel="self" href="http://myhost:8085/rest/api/latest/chart/reports" />
- <reports size="7" max-result="7" start-index="0">
- <report>
<key>com.atlassian.bamboo.plugin.system.reports:numberOfBuilds</key>
<name>Build Activity</name>
</report>
- <report>
<key>com.atlassian.bamboo.plugin.system.reports:averageDuration</key>
<name>Build Duration</name>
</report>
- <report>
<key>com.atlassian.bamboo.plugin.system.reports:averageQueuedDuration</key>
<name>Build Queued Duration</name>
</report>
- <report>
<key>com.atlassian.bamboo.plugin.myproject1:myproject1Coverage</key>
<name>My Project 1 Code Coverage</name>
</report>
- <report>
<key>com.atlassian.bamboo.plugin.myproject1:myproject1LinesOfCode</key>
<name>My Project 1 Lines of Code</name>
</report>
- <report>
<key>com.atlassian.bamboo.plugin.system.reports:numberOfFailures</key>
<name>Number of Build Failures</name>
</report>
- <report>
<key>com.atlassian.bamboo.plugin.system.reports:numberOfTests</key>
<name>Number of Tests</name>
</report>
</reports>
</reports>

Elements in the response:

Element

Attributes

report
  • key -- key of the Bamboo report
  • name -- name of the Bamboo report

Example of response JSON (list all available reports):

1
2
3
4
5
6
7
8
9
{"expand":"reports","link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/chart/reports"},
"reports":{"size":7,"max-result":7,"start-index":0,"report":[
{"key":"com.atlassian.bamboo.plugin.system.reports:numberOfBuilds","name":"Build Activity"},
{"key":"com.atlassian.bamboo.plugin.system.reports:averageDuration","name":"Build Duration"},
{"key":"com.atlassian.bamboo.plugin.system.reports:averageQueuedDuration","name":"Build Queued Duration"},
{"key":"com.atlassian.bamboo.plugin.myproject1:myproject1Coverage","name":"My Project 1 Code Coverage"},
{"key":"com.atlassian.bamboo.plugin.myproject1:myproject1LinesOfCode","name":"My Project 1 Lines of Code"},
{"key":"com.atlassian.bamboo.plugin.system.reports:numberOfFailures","name":"Number of Build Failures"},
{"key":"com.atlassian.bamboo.plugin.system.reports:numberOfTests","name":"Number of Tests"},

Build Queue Service

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

URI

/queue

Description

Lists all the builds waiting in the build queue, adds or removes a build from the build queue.

URI Parameters
  • no parameter – Displays the number of builds waiting in the build queue.
  • ?expand=queuedBuilds – Lists all the builds waiting in the build queue.
  • ?expand=queuedBuilds.queuedBuild.changes – Lists all the builds waiting in the build queue with associated changes expanded.

HTTP Methods
  • GET – Returns a list of projects.
  • POST – Adds a build to the build queue (e.g. /queue/MYPROJ1-MYPLAN1). No POST data required. Response will be empty.
  • DELETE – Removes a build from the build queue (e.g. /queue/MYPROJ1-MYPLAN1-BUILDNUMBER). Response will be empty.

Example command to trigger a build or delete it from the queue:

1
2
curl -X POST --user admin:admin http://host:8085/rest/api/latest/queue/PLAN-KEY?os_authType=basic
curl -X DELETE --user admin:admin http://host:8085/rest/api/latest/queue/PLAN-KEY?os_authType=basic

Example of response XML (retrieving builds in the build queue):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <queue expand="queuedBuilds">
<link rel="self" href="http://myhost:8085/rest/api/latest/queue"/>
- <queuedBuilds expand="queuedBuild" size="1" max-result="1" start-index="0">
- <queuedBuild buildResultKey="MYPROJ1-MYPLAN1-7" buildNumber="7" planKey="MYPROJ1-MYPLAN1" expand="changes">
<triggerReason>Manual build</triggerReason>
- <changes expand="change" size="1" max-result="1" start-index="0">
<change changesetId="98662" author="apowers"/>
</changes>
</queuedBuild>
</queuedBuilds>
</queue>

Elements in the response:

Element

Attributes

queue/queuedBuilds
  • size -- Number of builds in the build queue

queue/queuedBuilds/queuedBuild
  • buildResultKey -- Key for the build result
  • buildNumber -- Build number
  • planKey -- Key for the build plan

queue/queuedBuilds/queuedBuild/triggerReason

Description: Build trigger reason

queue/queuedBuilds/queuedBuild/changes
  • size -- Number of changes associated with build

queue/queuedBuilds/queuedBuild/changes/change
  • changesetId -- Id of the changeset
  • author -- Author of the changeset

Example of response JSON:

1
2
3
4
5
6
7
8
{"expand":"queuedBuilds","link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/queue"},
"queuedBuilds":{"expand":"queuedBuild","size":1,"max-result":1,"start-index":0,"queuedBuild":[
{"buildResultKey":"MYPROJ1-MYPLAN1-7","buildNumber":7,"planKey":"MYPROJ1-MYPLAN1","expand":"changes","triggerReason":"Manual build",
"changes":
{"expand":"change","size":1,"max-result":1,"start-index":0,"change":[
{"changesetId":"98662","author":"apowers"}
]}}
]}}

Comments Service

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

URI

/result/PROJECTKEY-PLANKEY-BUILDNUMBER/comment

Description

Retrieves the comments for a build result, adds a comment to a build result.

URI Parameters
  • no parameter – Retrieves the comments for a build result.
  • ?expand=comments.comment – Retrieves the comments for a build result with expanded comment details.

HTTP Methods
  • GET – Retrieves the comments for a build result.
  • POST – Adds a comment to the build result. Response will be empty.

Example of response XML (retrieving comments for a build result):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <comments expand="comments">
<link rel="self" href="http://myhost:8085/rest/api/latest/build/MYPROJ1-MYPLAN1-5/comment"/>
- <comments expand="comment" size="1" max-result="1" start-index="0">
- <comment author="apowers">
<content>Groovy build result baby!</content>
<creationDate>2009-09-11T22:35:34.436+0200</creationDate>
<modificationDate>2009-09-11T22:35:34.436+0200</modificationDate>
</comment>
</comments>
</comments>

Elements in the response:

Element

Attributes

comments/link
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the comment

comments/comments
  • size -- Number of comments for the build result

comments/comments/comment
  • author -- Author of the comment

comments/comments/comment/content

Description: Content of the comment

comments/comments/comment/creationDate

Description: Creation date of the comment

comments/comments/comment/modificationDate

Description: Last modified date of the comment

Example of response JSON:

1
2
3
4
5
6
7
{"expand":"comments","link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/build/MYPROJ1-MYPLAN1-5/comment"},"comments":
{"expand":"comment","size":1,"max-result":1,"start-index":0,"comment":[
{"author":"apowers",
"content":"Groovy build result baby!",
"creationDate":"2009-09-11T22:35:34.436+0200",
"modificationDate":"2009-09-11T22:35:34.436+0200"}
]}}

Example of request XML (posting a comment to a build result):

1
2
3
4
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <comment author="apowers">
<content>A build result comment.</content>
</comment>

Elements in the request:

Element

Attributes

comment
  • author -- The author of the comment

comment/content

Description: Content of the comment to be added to the build result

Labels Service

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

URI

/build/PROJECTKEY-PLANKEY-BUILDNUMBER/label

Description

Retrieves the labels for a build result, adds or removes a label to a build result.

URI Parameters
  • no parameter – Retrieves the labels for a build result.

HTTP Methods
  • GET – Retrieves the labels for a build result.
  • POST – Adds a label to the build result. Response will be empty.
  • DELETE – Removes a label from the build result, build/PROJECTKEY-PLANKEY-BUILDNUMBER/label/labelname e.g. Response will be empty.

Example of response XML (retrieving labels for a build result):

1
2
3
4
5
6
7
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <labels expand="labels">
<link rel="self" href="http://myhost:8085/rest/api/latest/build/MYPROJ1-MYPLAN1-5/label"/>
- <labels size="1" max-result="1" start-index="0">
<label name="label1"/>
</labels>
</labels>

Elements in the response:

Element

Attributes

labels/link
  • rel -- Relationship between link and element (defaults to "self")
  • href -- URL for the label

labels/labels
  • size -- Number of labels for the build result

labels/labels/label
  • name -- Name of the label

Example of response JSON:

1
2
3
4
{"expand":"labels","link":{"rel":"self","href":"http://myhost:8085/rest/api/latest/build/MYPROJ1-MYPLAN1-5/label"},
"labels":{"size":1,"max-result":1,"start-index":0,"label":[
{"name":"label1"}
]}}

Example of request XML (adding a label to a build result):

1
2
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<label name="label1" />

Elements in the request:

Element

Attributes

label
  • name -- The name of the label

Server Information Service

API reference for the latest Bamboo version is the recommended source of information on Bamboo REST APIs.

URI

/info

Description

Retrieves information about a Bamboo server.

URI Parameters
  • no parameter – Retrieves information about a Bamboo server.

HTTP Methods
  • GET – Retrieves information about a Bamboo server.

Example of response XML:

1
2
3
4
5
6
7
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
- <info>
<version>2.4</version>
<edition/>
<buildDate>2009-09-11T20:47:44.000+0200</buildDate>
<buildNumber>1503</buildNumber>
</info>

Elements in the response:

Element

Attributes

info/version

Description: Bamboo version of server

info/buildDate

Description: Server build date

info/buildNumber

Description: Server build number

Example of response JSON:

1
{"version":"2.4","edition":"","buildDate":"2009-09-11T20:47:44.000+0200","buildNumber":"1503"}