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]
<result id="2818060" expand="changes,testResults, metadata, logEntries,artifacts,comments, labels,jiraIssues" number="11"> lifeCycleState="Finished" state="Successful"  key="PROJECTKEY-PLANKEY-JOB1-11"

<link rel="self" href="http://localhost:8085/bamboo/rest/api/latest/result/PROJECTKEY-PLANKEY-JOB1-11"/>

<parent rel="parent" href="http://localhost:8085/bamboo/rest/api/latest/result/PROJECTKEY-PLANKEY-11"/>

<planName>My plan</planName>

<projectName>My project</projectName>

<stage>Default Stage</stage>

</result>

The same content in JSON:
[expand]
{id:"2818060",
expand:"changes,testResults, metadata, logEntries,artifacts,comments, labels,jiraIssues",
number:"11"
lifeCycleState:"Finished"
state:"Successful"
key:"PROJECT_KEY-PLANKEY-JOB1-11"
link:[{href:"http://localhost:8085/bamboo/rest/api/latest/result/PROJECTKEY-PLANKEY-JOB1-11",rel:"self"}],
parent:[{href:"http://localhost:8085/bamboo/rest/api/latest/result/PROJECTKEY-PLANKEY-11",rel:"parent"}],
planName:"My plan",
projectName:"My project",
stage:"Default Stage}}

Resources List

This document the current REST API provided by Bamboo.

Resources

/elasticConfiguration

Methods

GET

available response representations:

  • application/json (elasticConfiguration) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="elasticConfiguration" type="restElasticImageConfig"/><xs:element name="elasticConfiguration" type="restElasticImageConfig"/>

POST

acceptable request representations:

  • application/json (elasticConfiguration) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="elasticConfiguration" type="restElasticImageConfig"/><xs:element name="elasticConfiguration" type="restElasticImageConfig"/>

available response representations:

  • application/json (elasticConfiguration) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="elasticConfiguration" type="restElasticImageConfig"/><xs:element name="elasticConfiguration" type="restElasticImageConfig"/>

/elasticConfiguration/{configurationId}

resource-wide template parameters
parameter value description

configurationId

long

Methods

GET

available response representations:

  • application/json (elasticConfiguration) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="elasticConfiguration" type="restElasticImageConfig"/><xs:element name="elasticConfiguration" type="restElasticImageConfig"/>

PUT

acceptable request representations:

  • application/json (elasticConfiguration) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="elasticConfiguration" type="restElasticImageConfig"/><xs:element name="elasticConfiguration" type="restElasticImageConfig"/>

available response representations:

  • application/json (elasticConfiguration) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="elasticConfiguration" type="restElasticImageConfig"/><xs:element name="elasticConfiguration" type="restElasticImageConfig"/>

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:

/project?showEmpty

Methods

GET

Method used to list all projects defined in Bamboo. Projects without any plan are not listed by default, unless <em>showEmpty</em> query param is set to true. <p> Possible expand parameters: <dl> <dt>projects</dt><dd>list of projects projects.project - list of projects with project details</dd> <dt>projects.project.plans</dt><dd>list of project details and plans for project</dd> <dt>projects.project.plans.plan</dt><dd>list of project details and plans for project with plan details</dd> </dl>

request query parameters
parameter value description

showEmpty

boolean

available response representations:

  • application/xml (projects) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="projects" type="restProjects"/><xs:element name="projects" type="restProjects"/>
  • application/json (projects) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="projects" type="restProjects"/><xs:element name="projects" type="restProjects"/>

/project/{projectKey}?showEmpty

resource-wide template parameters
parameter value description

projectKey

string

project key

Methods

GET

Method used to retrieve information for project specified as project key. <p> Possible expand parameters: <dl> <dt>plans</dt><dd>list of plans for project</dd> <dt>plans.plan</dt><dd>list of plans with plan details (only plans visible - READ permission for user)</dd> <dt>plans.plan.actions</dt><dd>list of plans with plan details and actions available for user for plan</dd> </dl>

request query parameters
parameter value description

showEmpty

boolean

available response representations:

  • 404 [expand]

    Returned when specified project does not exist or project has no plans unless <em>showEmpty</em> param is true

DELETE

Marks project for deletion. Project will be deleted by a batch job.

available response representations:

  • 400 [expand]

    Returned when project can't be removed, e.g. when it contains any plans

  • 401 [expand]

    Returned when user has no administration permission to project

  • 204 [expand]

    Returned when project is successfully marked for deletion.

  • 404 [expand]

    Returned when project doesn't exist

/project/{projectKey}/repository

resource-wide template parameters
parameter value description

projectKey

string

Methods

GET

Fetch list of repositories which granted to create plan in given project by Repository stored Bamboo Specs. Returns json array: [{"id":"123", "name":"repo1", "url":"http://localhost:8085/admin/configureLinkedRepositories.action?repositoryId=123"}]

available response representations:

  • 200 [expand]

    The page object with list of repositories.

  • 403 [expand]

    Returned when user has no Administration permission to project

  • 404 [expand]

    Returned when specified project does not exist

POST

Grant permission to create/edit plan in given project by Bamboo Specs from given repository.

acceptable request representations:

  • application/xml (restIdContainer) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="restIdContainer" type="restIdContainer"/><xs:element name="restIdContainer" type="restIdContainer"/>
  • application/json (restIdContainer) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="restIdContainer" type="restIdContainer"/><xs:element name="restIdContainer" type="restIdContainer"/>

available response representations:

  • 201 [expand]

    added repository entity.

  • 400 [expand]

    Returned when idContainer is empty or null

  • 403 [expand]

    Returned when user has no Administration permission to project

  • 404 [expand]

    Returned when specified project does not exist or repository not found by id

/project/{projectKey}/repository/{repositoryId}

resource-wide template parameters
parameter value description

projectKey

string

project key

repositoryId

long

linked repository root id

Methods

DELETE

Remove approval to create plans in given project by given repository

available response representations:

  • 204 [expand]

    When successfully removed link between project and repository.

  • 403 [expand]

    Returned when user has no Administration permission to project

  • 404 [expand]

    Returned when specified project or repository does not exist

/project/{projectKey}/repository/search?searchTerm

resource-wide template parameters
parameter value description

projectKey

string

Methods

GET

Search for linked repositories which can be granted to create plans by Repository stored Bamboo Specs in given project

request query parameters
parameter value description

searchTerm

string

available response representations:

  • 200 [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restRepositoryList start-index="0" max-result="1" size="2">
        <searchResults>
            <id>123</id>
            <name>linked repository 1</name>
            <url>http://localhost:8085/admin/configureLinkedRepositories.action?repositoryId=123</url>
            <rssEnabled>true</rssEnabled>
        </searchResults>
        <searchResults>
            <id>321</id>
            <name>linked repository 2</name>
            <url>http://localhost:8085/admin/configureLinkedRepositories.action?repositoryId=321</url>
            <rssEnabled>true</rssEnabled>
        </searchResults>
    </restRepositoryList>
    

    The page object with list of repositories.

  • 403 [expand]

    Returned when user has no Administration permission to project

  • 404 [expand]

    Returned when specified project does not exist

/deploy/version

Methods

/deploy/version/{deploymentVersionId}/status

resource-wide template parameters
parameter value description

deploymentVersionId

long

deployment version id

Methods

GET

Get current status of deployment version.

available response representations:

  • 200 - application/json (restDeploymentVersionStatus) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <deploymentVersionStatus>
        <id>1</id>
        <userName>admin</userName>
        <displayName>Approved</displayName>
        <gravatarUrl></gravatarUrl>
        <creationDate>2018-09-25T13:29:33.717Z</creationDate>
        <versionState>APPROVED</versionState>
    </deploymentVersionStatus>
    

    XML Schema

    Source: xsd0.xsd

    <xs:complexType name="restDeploymentVersionStatus">
        <xs:sequence>
          <xs:element name="id" type="xs:long"/>
          <xs:element name="userName" type="xs:string" minOccurs="0"/>
          <xs:element name="displayName" type="xs:string" minOccurs="0"/>
          <xs:element name="gravatarUrl" type="xs:string" minOccurs="0"/>
          <xs:element name="creationDate" type="xs:dateTime" minOccurs="0"/>
          <xs:element name="versionState" type="deploymentVersionState" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType><xs:complexType name="restDeploymentVersionStatus">
        <xs:sequence>
          <xs:element name="id" type="xs:long"/>
          <xs:element name="userName" type="xs:string" minOccurs="0"/>
          <xs:element name="displayName" type="xs:string" minOccurs="0"/>
          <xs:element name="gravatarUrl" type="xs:string" minOccurs="0"/>
          <xs:element name="creationDate" type="xs:dateTime" minOccurs="0"/>
          <xs:element name="versionState" type="deploymentVersionState" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType>
  • 404 [expand]

    deployment version not found

/deploy/version/{deploymentVersionId}/status/{newStatus}

resource-wide template parameters
parameter value description

deploymentVersionId

long

deployment version id

newStatus

string

deployment version status. Possible values: UNKNOWN, APPROVED, BROKEN, INCOMPLETE

Methods

POST

Update deployment version status.

available response representations:

  • 200 - application/json (restDeploymentVersionStatus) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <deploymentVersionStatus>
        <id>1</id>
        <userName>admin</userName>
        <displayName>Approved</displayName>
        <gravatarUrl></gravatarUrl>
        <creationDate>2018-09-25T13:29:33.717Z</creationDate>
        <versionState>APPROVED</versionState>
    </deploymentVersionStatus>
    

    XML Schema

    Source: xsd0.xsd

    <xs:complexType name="restDeploymentVersionStatus">
        <xs:sequence>
          <xs:element name="id" type="xs:long"/>
          <xs:element name="userName" type="xs:string" minOccurs="0"/>
          <xs:element name="displayName" type="xs:string" minOccurs="0"/>
          <xs:element name="gravatarUrl" type="xs:string" minOccurs="0"/>
          <xs:element name="creationDate" type="xs:dateTime" minOccurs="0"/>
          <xs:element name="versionState" type="deploymentVersionState" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType><xs:complexType name="restDeploymentVersionStatus">
        <xs:sequence>
          <xs:element name="id" type="xs:long"/>
          <xs:element name="userName" type="xs:string" minOccurs="0"/>
          <xs:element name="displayName" type="xs:string" minOccurs="0"/>
          <xs:element name="gravatarUrl" type="xs:string" minOccurs="0"/>
          <xs:element name="creationDate" type="xs:dateTime" minOccurs="0"/>
          <xs:element name="versionState" type="deploymentVersionState" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType>
  • 400 - application/json (restErrorCollection) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <errors>
        <errors>Unknown deployment version status: MY_STATUS</errors>
        <fieldErrors/>
    </errors>
    

    XML Schema

    Source:

  • 401 [expand]

    For not authorized user

  • 404 [expand]

    Deployment version was not found by deployment version id

/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:

/permissions/projectplan

REST endpoint to manage user/group project plan permissions in Bamboo. Project plan permission is permission applied on project and defines base permissions for plans in that project. Additional permission for given plans can be applied on a plan level.

Methods

/permissions/projectplan/{key}/users?name

resource-wide template parameters
parameter value description

key

string

project entity key

Methods

GET

Retrieve a list of users with their explicit permissions to given resource. The list can be filtered by some attributes. This resource is paged and returns a single page of results.

request query parameters
parameter value description

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/projectplan/{key}/users/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

username of the affected user

key

string

project entity key

Methods

PUT

Grants project plan permissions to a given user.

available response representations:

  • 400 [expand]

    If 'username' user doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If user already had requested permissions and permission state hasn't been changed.

DELETE

Revokes project plan permissions from a given user.

available response representations:

  • 400 [expand]

    If the 'username' user doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If user already lacked requested permissions and permission state hasn't been changed.

/permissions/projectplan/{key}/available-users?name

resource-wide template parameters
parameter value description

key

string

project entity key

Methods

GET

Returns list of users which weren't granted explicitly any project plan permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/projectplan/{key}/groups?name

resource-wide template parameters
parameter value description

key

string

project entity key

Methods

GET

Retrieve a list of groups with their project plan permissions. The list can be filtered by some attributes. This resource is paged returns a single page of results.

request query parameters
parameter value description

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/projectplan/{key}/groups/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

affected group

key

string

project entity key

Methods

PUT

Grants project plan permissions to a given group.

available response representations:

  • 400 [expand]

    If group doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If group already had requested permissions and permission state hasn't been changed.

DELETE

Revokes project plan permissions from a given group.

available response representations:

  • 400 [expand]

    If group doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If group already lacked requested permissions and permission state hasn't been changed.

/permissions/projectplan/{key}/available-groups?name

resource-wide template parameters
parameter value description

key

string

project entity key

Methods

GET

Returns list of groups which weren't granted explicitly any project plan permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/projectplan/{key}/roles

resource-wide template parameters
parameter value description

key

string

project entity key

Methods

GET

Retrieve a list of roles with their project plan permissions. This resource is paged returns a single page of results, although only 2 roles are supported: LOGGED IN users, ANONYMOUS users

available response representations:

  • 200 [expand]

    Return single page of roles with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/projectplan/{key}/roles/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

affected role

key

string

project entity key

Methods

PUT

Grants project plan permissions to a given role.

available response representations:

  • 400 [expand]

    If role doesn't exist or one of the requested permission isn't supported for given role. Anonymous role supports only VIEW permission.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If role already had requested permissions and permission state hasn't been changed.

DELETE

Revokes project plan permissions from a given role.

available response representations:

  • 400 [expand]

    If role doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If role already lacked requested permissions and permission state hasn't been changed.

/elasticInstances

Methods

/elasticInstances/instance/{instanceId}/logs

resource-wide template parameters
parameter value description

instanceId

string

id of the EC2 instance

Methods

GET

Obtain logs from an EC2 instance. Note that this method will return the console output of the instance, not Bamboo agent logs.

available response representations:

  • 200 - application/json [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <elasticInstanceLog>
        <instanceId>i-b8532d45</instanceId>
        <log>Transaction Summary
    ================================================================================
    Upgrade 5 Packages
    
    Total download size: 67 M
    Downloading packages:
    --------------------------------------------------------------------------------</log>
    </elasticInstanceLog>
    

    A JSON object containing the instance id and it's console output

  • 400 - application/json [expand]

    Returned when input or server state validation fails, for example when AWS account is not configured or Elastic Bamboo is not enabled.

  • 404 - application/json [expand]

    Returned when no EC2 instance with the given id was found. The instance has to exist and must be managed by this Bamboo server.

/clone

Methods

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

resource-wide template parameters
parameter value description

projectKey

string

buildKey

string

toBuildKey

string

toProjectKey

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]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="plan" type="restPlan"/><xs:element name="plan" type="restPlan"/>
  • application/json (plan) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="plan" type="restPlan"/><xs:element name="plan" type="restPlan"/>

/deploy/projectVersioning

Methods

/deploy/projectVersioning/{deploymentProjectId}/variables

resource-wide template parameters
parameter value description

deploymentProjectId

long

deployment project id

Methods

GET

Get variables associated with deployment project.

available response representations:

  • 200 - application/json (versionVariables) [expand]
    XML Schema

    Source:

  • 400 [expand]

    Validation error

  • 404 [expand]

    Deployment project not found

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

resource-wide template parameters
parameter value description

deploymentProjectId

long

deployment project id

Methods

GET

Get deployment version name preview.

request query parameters
parameter value description

nextVersionName

string

name version. Mandatory

incrementNumbers

boolean

if version number should be incremented

incrementableVariables

string

variables used for version name. Divided by coma

available response representations:

  • 200 - application/json (restNamingPreview) [expand]
    XML Schema

    Source:

  • 400 - application/json [expand]

    Validation error

  • 404 [expand]

    Deployment project not found

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

resource-wide template parameters
parameter value description

deploymentProjectId

long

deployment project id

Methods

GET

Get next deployment version name

request query parameters
parameter value description

resultKey

string

build result key

available response representations:

  • 200 - application/json (restNamingPreview) [expand]
    XML Schema

    Source:

  • 400 - application/json [expand]

    Validation error

  • 404 [expand]

    Deployment project not found

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

resource-wide template parameters
parameter value description

deploymentProjectId

long

deployment project id

Methods

GET

Extract variables value from version name.

request query parameters
parameter value description

nextVersionName

string

version name

available response representations:

  • 200 - application/json [expand]
  • 400 - application/json [expand]

    Validation error

  • 404 [expand]

    Deployment project not found

/permissions/environment

REST endpoint to manage user/group deployment environment permissions in Bamboo.

Methods

/permissions/environment/{id}/users?name

resource-wide template parameters
parameter value description

id

string

deployment environment entity key

Methods

GET

Retrieve a list of users with their explicit permissions to given resource. The list can be filtered by some attributes. This resource is paged and returns a single page of results.

request query parameters
parameter value description

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/environment/{id}/users/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

username of the affected user

id

string

deployment environment entity key

Methods

PUT

Grants deployment environment permissions to a given user.

available response representations:

  • 400 [expand]

    If 'username' user doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If user already had requested permissions and permission state hasn't been changed.

DELETE

Revokes deployment environment permissions from a given user.

available response representations:

  • 400 [expand]

    If the 'username' user doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If user already lacked requested permissions and permission state hasn't been changed.

/permissions/environment/{id}/available-users?name

resource-wide template parameters
parameter value description

id

string

deployment environment entity key

Methods

GET

Returns list of users which weren't granted explicitly any deployment environment permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/environment/{id}/groups?name

resource-wide template parameters
parameter value description

id

string

deployment environment entity key

Methods

GET

Retrieve a list of groups with their deployment environment permissions. The list can be filtered by some attributes. This resource is paged returns a single page of results.

request query parameters
parameter value description

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/environment/{id}/groups/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

affected group

id

string

deployment environment entity key

Methods

PUT

Grants deployment environment permissions to a given group.

available response representations:

  • 400 [expand]

    If group doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If group already had requested permissions and permission state hasn't been changed.

DELETE

Revokes deployment environment permissions from a given group.

available response representations:

  • 400 [expand]

    If group doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If group already lacked requested permissions and permission state hasn't been changed.

/permissions/environment/{id}/available-groups?name

resource-wide template parameters
parameter value description

id

string

deployment environment entity key

Methods

GET

Returns list of groups which weren't granted explicitly any deployment environment permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/environment/{id}/roles

resource-wide template parameters
parameter value description

id

string

deployment environment entity key

Methods

GET

Retrieve a list of roles with their deployment environment permissions. This resource is paged returns a single page of results, although only 2 roles are supported: LOGGED IN users, ANONYMOUS users

available response representations:

  • 200 [expand]

    Return single page of roles with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/environment/{id}/roles/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

affected role

id

string

deployment environment entity key

Methods

PUT

Grants deployment environment permissions to a given role.

available response representations:

  • 400 [expand]

    If role doesn't exist or one of the requested permission isn't supported for given role. Anonymous role supports only VIEW permission.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If role already had requested permissions and permission state hasn't been changed.

DELETE

Revokes deployment environment permissions from a given role.

available response representations:

  • 400 [expand]

    If role doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If role already lacked requested permissions and permission state hasn't been changed.

/currentUser

Methods

GET

available response representations:

  • application/json (userBean) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="userBean" type="userBean"/><xs:element name="userBean" type="userBean"/>
  • application/xml (userBean) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="userBean" type="userBean"/><xs:element name="userBean" type="userBean"/>

/permissions/repository

REST endpoint to manage user/group repository permissions in Bamboo.

Methods

/permissions/repository/{id}/users?name

resource-wide template parameters
parameter value description

id

string

repository entity key

Methods

GET

Retrieve a list of users with their explicit permissions to given resource. The list can be filtered by some attributes. This resource is paged and returns a single page of results.

request query parameters
parameter value description

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/repository/{id}/users/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

username of the affected user

id

string

repository entity key

Methods

PUT

Grants repository permissions to a given user.

available response representations:

  • 400 [expand]

    If 'username' user doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If user already had requested permissions and permission state hasn't been changed.

DELETE

Revokes repository permissions from a given user.

available response representations:

  • 400 [expand]

    If the 'username' user doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If user already lacked requested permissions and permission state hasn't been changed.

/permissions/repository/{id}/available-users?name

resource-wide template parameters
parameter value description

id

string

repository entity key

Methods

GET

Returns list of users which weren't granted explicitly any repository permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/repository/{id}/groups?name

resource-wide template parameters
parameter value description

id

string

repository entity key

Methods

GET

Retrieve a list of groups with their repository permissions. The list can be filtered by some attributes. This resource is paged returns a single page of results.

request query parameters
parameter value description

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/repository/{id}/groups/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

affected group

id

string

repository entity key

Methods

PUT

Grants repository permissions to a given group.

available response representations:

  • 400 [expand]

    If group doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If group already had requested permissions and permission state hasn't been changed.

DELETE

Revokes repository permissions from a given group.

available response representations:

  • 400 [expand]

    If group doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If group already lacked requested permissions and permission state hasn't been changed.

/permissions/repository/{id}/available-groups?name

resource-wide template parameters
parameter value description

id

string

repository entity key

Methods

GET

Returns list of groups which weren't granted explicitly any repository permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/repository/{id}/roles

resource-wide template parameters
parameter value description

id

string

repository entity key

Methods

GET

Retrieve a list of roles with their repository permissions. This resource is paged returns a single page of results, although only LOGGED IN users role is supported.

available response representations:

  • 200 [expand]

    Return single page of roles with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/repository/{id}/roles/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

affected role

id

string

repository entity key

Methods

PUT

Grants repository permissions to a given role.

available response representations:

  • 400 [expand]

    If role doesn't exist or one of the requested permission isn't supported for given role.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If role already had requested permissions and permission state hasn't been changed.

DELETE

Revokes repository permissions from a given role.

available response representations:

  • 400 [expand]

    If role doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If role already lacked requested permissions and permission state hasn't been changed.

/dependency

Methods

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

resource-wide template parameters
parameter value description

projectKey

string

buildKey

string

Methods

GET

Search for available plan child dependencies

request query parameters
parameter value description

searchTerm

string

available response representations:

  • application/xml (dependencies) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="dependencies" type="restDependencies"/><xs:element name="dependencies" type="restDependencies"/>
  • application/json (dependencies) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="dependencies" type="restDependencies"/><xs:element name="dependencies" type="restDependencies"/>

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

resource-wide template parameters
parameter value description

projectKey

string

buildKey

string

Methods

GET

Search for available plan parent dependencies

request query parameters
parameter value description

searchTerm

string

available response representations:

  • application/xml (dependencies) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="dependencies" type="restDependencies"/><xs:element name="dependencies" type="restDependencies"/>
  • application/json (dependencies) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="dependencies" type="restDependencies"/><xs:element name="dependencies" type="restDependencies"/>

/deploy/environment/{environmentId}/requirement

Provides RESTful operations on deployment environment requirements.

resource-wide template parameters
parameter value description

environmentId

long

Methods

GET

Gets all the requirements of an environment.

available response representations:

  • 200 (200) [expand]

    A list of a requirements

    XML Schema

    Source:

  • 401 [expand]

    If the user lack permissions for retrieving details about the environment structure, which translates into WRITE permissions to view and edit the environment configuration

  • 404 [expand]

    If the specified environment id is not found

POST

Adds a requirement for a given environment.

acceptable request representations:

  • application/json (requirement) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <requirement>
        <id>-1</id>
        <key>REQ-KEY</key>
        <matchType>EXISTS</matchType>
        <readonlyData/>
        <operations>
            <canEdit>true</canEdit>
            <canDelete>true</canDelete>
        </operations>
    </requirement>
    

    XML Schema

    Source: xsd0.xsd

    <xs:element name="requirement" type="restRequirement"/><xs:element name="requirement" type="restRequirement"/>

available response representations:

  • 200 (200) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <requirement>
        <id>-1</id>
        <key>REQ-KEY</key>
        <matchType>EXISTS</matchType>
        <readonlyData/>
        <operations>
            <canEdit>true</canEdit>
            <canDelete>true</canDelete>
        </operations>
    </requirement>
    

    The updated requirement

    XML Schema

    Source:

  • 403 [expand]

    If the user has no permissions to add a requirement to an environment, which translates into no WRITE permissions to edit the configuration of the environment it belongs to

  • 404 [expand]

    If the environment id is not found

/deploy/environment/{environmentId}/requirement/summary

resource-wide template parameters
parameter value description

environmentId

long

environmentId

long

Methods

GET

Gets a summary of the agents that are capable of running an environment, based of its requirements.

available response representations:

  • 200 (200) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restAgentSummary>
        <matchingAgentsCount>0</matchingAgentsCount>
        <matchingImagesCount>0</matchingImagesCount>
        <onlineEnabledAgentsCount>0</onlineEnabledAgentsCount>
        <isElasticBambooEnabled>false</isElasticBambooEnabled>
        <requirementsCountWithNoMatches>0</requirementsCountWithNoMatches>
        <requirementsCount>0</requirementsCount>
        <canConfigureAgents>true</canConfigureAgents>
        <canConfigureImages>true</canConfigureImages>
        <hasDedicatedExecutors>false</hasDedicatedExecutors>
    </restAgentSummary>
    

    a summary of the agents that can run an environment

    XML Schema

    Source:

  • 401 [expand]

    if the user does not have permissions to get information about the environment.

  • 404 [expand]

    If the specified environment id is not found

/deploy/environment/{environmentId}/requirement/detailedSummary

resource-wide template parameters
parameter value description

environmentId

long

environmentId

long

Methods

GET

Gets a detailed summary of the agents that are capable of running an environment, based of its requirements.

available response representations:

  • 200 (200) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restAgentSummary>
        <matchingAgentsCount>0</matchingAgentsCount>
        <matchingImagesCount>0</matchingImagesCount>
        <onlineEnabledAgentsCount>0</onlineEnabledAgentsCount>
        <isElasticBambooEnabled>false</isElasticBambooEnabled>
        <requirementsCountWithNoMatches>0</requirementsCountWithNoMatches>
        <requirementsCount>0</requirementsCount>
        <canConfigureAgents>true</canConfigureAgents>
        <canConfigureImages>true</canConfigureImages>
        <hasDedicatedExecutors>false</hasDedicatedExecutors>
    </restAgentSummary>
    

    a summary of the agents that can run an environment

    XML Schema

    Source:

  • 401 [expand]

    if the user does not have permissions to get information about the environment.

  • 404 [expand]

    If the specified environment id is not found

/deploy/environment/{environmentId}/requirement/{id}

resource-wide template parameters
parameter value description

environmentId

long

environmentId

long

id

long

Methods

GET

Gets the details of a requirement for a given environment.

available response representations:

  • 200 (200) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <requirement>
        <id>-1</id>
        <key>REQ-KEY</key>
        <matchType>EXISTS</matchType>
        <readonlyData/>
        <operations>
            <canEdit>true</canEdit>
            <canDelete>true</canDelete>
        </operations>
    </requirement>
    

    A representation of a requirement

    XML Schema

    Source:

  • 403 [expand]

    If the user lack permissions for retrieving details about the environment, which translates into WRITE permissions to view and edit the environment

  • 404 [expand]

    If the specified environment id is not found or the requirement id does not exist

/deploy/environment/{environmentId}/requirement/{requirementId}

resource-wide template parameters
parameter value description

environmentId

long

environmentId

long

environment id

requirementId

long

requirement id of the requirement to delete

Methods

PUT

Updates a requirement for a given environment.

acceptable request representations:

  • application/json (requirement) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <requirement>
        <id>-1</id>
        <key>REQ-KEY</key>
        <matchType>EXISTS</matchType>
        <readonlyData/>
        <operations>
            <canEdit>true</canEdit>
            <canDelete>true</canDelete>
        </operations>
    </requirement>
    

    XML Schema

    Source: xsd0.xsd

    <xs:element name="requirement" type="restRequirement"/><xs:element name="requirement" type="restRequirement"/>

available response representations:

  • 200 (200) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <requirement>
        <id>-1</id>
        <key>REQ-KEY</key>
        <matchType>EXISTS</matchType>
        <readonlyData/>
        <operations>
            <canEdit>true</canEdit>
            <canDelete>true</canDelete>
        </operations>
    </requirement>
    

    The updated requirement

    XML Schema

    Source:

  • 403 [expand]

    If the user has no permissions for updating a requirement, which translates into no WRITE permissions to edit the configuration of the environment it belongs to

  • 404 [expand]

    If the environment id is not found, or the requirement id does not exist

DELETE

Removes a requirement for an environment.

available response representations:

  • 401 [expand]

    If the user lacks permissions to remove an environment requirement, which translates into no WRITE permissions to edit the environment

  • 204 [expand]

    The environment's requirement has been deleted successfully

  • 404 [expand]

    If the environment id is not found, or the requirement it does not exist

/queue/deployment?expand

Methods

GET

Provide list of deployment results scheduled for execution and waiting in queue.

request query parameters
parameter value description

expand

string

expands deployment result queue items on request. Possible value: queuedDeployments.

available response representations:

  • 200 - application/json (restQueuedDeployments) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <queue expand="queuedDeployments">
        <queuedDeployments start-index="0" max-result="2" size="0">
            <queuedDeployments>
                <deploymentResultId>12</deploymentResultId>
            </queuedDeployments>
            <queuedDeployments>
                <deploymentResultId>25</deploymentResultId>
            </queuedDeployments>
        </queuedDeployments>
    </queue>
    

    XML Schema

    Source:

POST

Trigger deployment for deployment environment and version.

request query parameters
parameter value description

environmentId

long

Deployment environment id. Mandatory

versionId

long

Version (release) id. Mandatory

available response representations:

  • 200 - application/json (restQueuedDeployment) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restQueuedDeployment>
        <deploymentResultId>12</deploymentResultId>
    </restQueuedDeployment>
    

    Trigger deployment for environment and version

    XML Schema

    Source:

  • 400 - application/json (restValidationError) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <errors>
        <errors>Deployment environment with id 1 and deployment version with id 2 are from different deployment projects</errors>
        <fieldErrors/>
    </errors>
    

    Validation error occurred or deployment can't be triggered

    XML Schema

    Source:

  • 403 - application/json [expand]

    User don't have permissions to trigger deployment to given environment

  • 404 [expand]

    Environment or version are not found

/queue/deployment/{deploymentResultId}

resource-wide template parameters
parameter value description

deploymentResultId

long

id of deployment result in queue.

Methods

DELETE

Remove deployment result from queue.

available response representations:

  • 400 - application/json (restValidationError) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <errors>
        <errors>Deployment can't be removed from queue as it's in finished state</errors>
        <fieldErrors/>
    </errors>
    

    Deployment already finished and can't be removed from queue

    XML Schema

    Source:

  • 204 [expand]

    Successfully removed deployment result from queue

  • 403 - application/json [expand]

    User don't have permission to delete deployment from queue

  • 404 [expand]

    Can't find deployment result by deploymentResultId

/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]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="versionPreview" type="versionPreview"/><xs:element name="versionPreview" type="versionPreview"/>

/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]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="versionPreview" type="versionPreview"/><xs:element name="versionPreview" type="versionPreview"/>

/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:

/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]

    Returns status of the current indexing operation

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]

    Returns status of the current indexing operation

/search

Methods

/search/jobs/{planKey}?searchTerm

resource-wide template parameters
parameter value description

planKey

string

planKey for plan where jobs will be searched for

Methods

GET

Performs a "starts with" search against full job name and full job 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]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>
  • application/json (searchResults) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>

/search/stages/{planKey}?stageId&searchTerm

resource-wide template parameters
parameter value description

planKey

string

Methods

GET

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

request query parameters
parameter value description

stageId

string

searchTerm

string

available response representations:

  • application/xml (searchResults) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>
  • application/json (searchResults) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>

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

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

fuzzy

boolean

available response representations:

  • application/xml (searchResults) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>
  • application/json (searchResults) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>

/search/projects?searchTerm&permission

Methods

GET

Performs a contains search against project name.

request query parameters
parameter value description

searchTerm

string

to search for. Optional

permission

string

only return those projects that querying user has permission to ({@link BambooPermission}. Default is READ.

available response representations:

  • application/xml (searchResults) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>
  • application/json (searchResults) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>

/search/deployments?searchTerm&permission

Methods

GET

Performs a contains search against deployment project name.

request query parameters
parameter value description

searchTerm

string

to search for. Optional

permission

string

only return those deployment projects that querying user has permission to ({@link BambooPermission}. Default is READ.

available response representations:

  • application/xml (searchResults) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>
  • application/json (searchResults) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>

/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]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>
  • application/json (searchResults) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>

/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]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <searchResults start-index="0" max-result="1" size="1">
        <searchResults id="jsmith" type="user">
            <searchEntity xsi:type="userSearchResult" id="jsmith" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <username>jsmith</username>
                <fullName>John Smith</fullName>
                <displayableEmail>jsmith@example.com</displayableEmail>
                <avatarUrl>https://secure.gravatar.com/avatar/asdfasdfasdfasdf.jpg?d=mm&amp;s=16&amp;r=g</avatarUrl>
            </searchEntity>
        </searchResults>
    </searchResults>
    

    Search results for users matching the provided search term

    XML Schema

    Source: xsd0.xsd

    <xs:complexType name="searchResultsList">
        <xs:sequence>
          <xs:element name="searchResults" type="searchResult" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="start-index" type="xs:int" use="required"/>
        <xs:attribute name="max-result" type="xs:int" use="required"/>
        <xs:attribute name="size" type="xs:int" use="required"/>
      </xs:complexType><xs:complexType name="searchResultsList">
        <xs:sequence>
          <xs:element name="searchResults" type="searchResult" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="start-index" type="xs:int" use="required"/>
        <xs:attribute name="max-result" type="xs:int" use="required"/>
        <xs:attribute name="size" type="xs:int" use="required"/>
      </xs:complexType>

/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]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <searchResults start-index="0" max-result="1" size="1">
        <searchResults id="jsmith" type="author">
            <searchEntity xsi:type="authorSearchResult" id="jsmith" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <authorName>jsmith</authorName>
            </searchEntity>
        </searchResults>
    </searchResults>
    

    Search results for authors matching the provided search term

    XML Schema

    Source: xsd0.xsd

    <xs:complexType name="searchResultsList">
        <xs:sequence>
          <xs:element name="searchResults" type="searchResult" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="start-index" type="xs:int" use="required"/>
        <xs:attribute name="max-result" type="xs:int" use="required"/>
        <xs:attribute name="size" type="xs:int" use="required"/>
      </xs:complexType><xs:complexType name="searchResultsList">
        <xs:sequence>
          <xs:element name="searchResults" type="searchResult" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="start-index" type="xs:int" use="required"/>
        <xs:attribute name="max-result" type="xs:int" use="required"/>
        <xs:attribute name="size" type="xs:int" use="required"/>
      </xs:complexType>

/search/plans?searchTerm&fuzzy&type&permission

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

fuzzy

boolean

whether the search should be more relaxed when matching results. Default is false.

type

string

type of the plan to return ({@link PlanType}. Optional

permission

string

only return those plans that querying user has permission to ({@link BambooPermission}. Default is READ.

available response representations:

  • application/xml (searchResults) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>
  • application/json (searchResults) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>

/permissions/deployment

REST endpoint to manage user/group deployment project permissions in Bamboo.

Methods

/permissions/deployment/{id}/users?name

resource-wide template parameters
parameter value description

id

string

deployment project entity key

Methods

GET

Retrieve a list of users with their explicit permissions to given resource. The list can be filtered by some attributes. This resource is paged and returns a single page of results.

request query parameters
parameter value description

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/deployment/{id}/users/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

username of the affected user

id

string

deployment project entity key

Methods

PUT

Grants deployment project permissions to a given user.

available response representations:

  • 400 [expand]

    If 'username' user doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If user already had requested permissions and permission state hasn't been changed.

DELETE

Revokes deployment project permissions from a given user.

available response representations:

  • 400 [expand]

    If the 'username' user doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If user already lacked requested permissions and permission state hasn't been changed.

/permissions/deployment/{id}/available-users?name

resource-wide template parameters
parameter value description

id

string

deployment project entity key

Methods

GET

Returns list of users which weren't granted explicitly any deployment project permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/deployment/{id}/groups?name

resource-wide template parameters
parameter value description

id

string

deployment project entity key

Methods

GET

Retrieve a list of groups with their deployment project permissions. The list can be filtered by some attributes. This resource is paged returns a single page of results.

request query parameters
parameter value description

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/deployment/{id}/groups/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

affected group

id

string

deployment project entity key

Methods

PUT

Grants deployment project permissions to a given group.

available response representations:

  • 400 [expand]

    If group doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If group already had requested permissions and permission state hasn't been changed.

DELETE

Revokes deployment project permissions from a given group.

available response representations:

  • 400 [expand]

    If group doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If group already lacked requested permissions and permission state hasn't been changed.

/permissions/deployment/{id}/available-groups?name

resource-wide template parameters
parameter value description

id

string

deployment project entity key

Methods

GET

Returns list of groups which weren't granted explicitly any deployment project permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/deployment/{id}/roles

resource-wide template parameters
parameter value description

id

string

deployment project entity key

Methods

GET

Retrieve a list of roles with their deployment project permissions. This resource is paged returns a single page of results, although only 2 roles are supported: LOGGED IN users, ANONYMOUS users

available response representations:

  • 200 [expand]

    Return single page of roles with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/deployment/{id}/roles/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

affected role

id

string

deployment project entity key

Methods

PUT

Grants deployment project permissions to a given role.

available response representations:

  • 400 [expand]

    If role doesn't exist or one of the requested permission isn't supported for given role. Anonymous role supports only VIEW permission.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If role already had requested permissions and permission state hasn't been changed.

DELETE

Revokes deployment project permissions from a given role.

available response representations:

  • 400 [expand]

    If role doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If role already lacked requested permissions and permission state hasn't been changed.

/deploy/environment

Methods

/deploy/environment/{environmentId}/results?expand

resource-wide template parameters
parameter value description

environmentId

long

deployment environment id

Methods

GET

Provide list of versions deployed to environment

request query parameters
parameter value description

expand

string

expands deployment versions. Possible values are: results

available response representations:

  • 200 - application/json (restDeploymentResultList) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restDeploymentResultList expand="results" start-index="0" max-result="2" size="2">
        <results>
            <deploymentVersion>
                <id>15</id>
                <name>version1</name>
                <creationDate>2018-09-25T13:29:33.458Z</creationDate>
                <creatorUserName>Administrator User</creatorUserName>
                <versionStatus>
                    <id>1</id>
                    <userName>admin</userName>
                    <displayName>Approved</displayName>
                    <gravatarUrl></gravatarUrl>
                    <creationDate>2018-09-25T13:29:33.464Z</creationDate>
                    <versionState>APPROVED</versionState>
                </versionStatus>
                <operations>
                    <canView>true</canView>
                    <canEdit>true</canEdit>
                    <canDelete>false</canDelete>
                    <allowedToExecute>false</allowedToExecute>
                    <canExecute>false</canExecute>
                    <cantExecuteReason>Not authorized</cantExecuteReason>
                    <allowedToCreateVersion>false</allowedToCreateVersion>
                    <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
                </operations>
                <creatorDisplayName>Administrator User</creatorDisplayName>
                <creatorGravatarUrl></creatorGravatarUrl>
                <planBranchName>PLAN12</planBranchName>
                <ageZeroPoint>2018-09-25T13:29:33.465Z</ageZeroPoint>
            </deploymentVersion>
            <deploymentVersionName>release-1</deploymentVersionName>
            <id>1</id>
            <deploymentState>SUCCESS</deploymentState>
            <lifeCycleState>FINISHED</lifeCycleState>
            <startedDate>2018-09-25T13:29:33.471Z</startedDate>
            <queuedDate>2018-09-25T13:29:33.471Z</queuedDate>
            <executedDate>2018-09-25T13:29:33.471Z</executedDate>
            <finishedDate>2018-09-25T13:29:33.471Z</finishedDate>
            <reasonSummary>Manual build</reasonSummary>
            <key>
                <key>123-123-1</key>
                <entityKey>
                    <key>123-123</key>
                </entityKey>
                <resultNumber>1</resultNumber>
            </key>
            <operations>
                <canView>true</canView>
                <canEdit>true</canEdit>
                <canDelete>false</canDelete>
                <allowedToExecute>false</allowedToExecute>
                <canExecute>false</canExecute>
                <cantExecuteReason>Not authorized</cantExecuteReason>
                <allowedToCreateVersion>false</allowedToCreateVersion>
                <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
            </operations>
        </results>
        <results>
            <deploymentVersion>
                <id>15</id>
                <name>version1</name>
                <creationDate>2018-09-25T13:29:33.482Z</creationDate>
                <creatorUserName>Administrator User</creatorUserName>
                <versionStatus>
                    <id>1</id>
                    <userName>admin</userName>
                    <displayName>Approved</displayName>
                    <gravatarUrl></gravatarUrl>
                    <creationDate>2018-09-25T13:29:33.482Z</creationDate>
                    <versionState>APPROVED</versionState>
                </versionStatus>
                <operations>
                    <canView>true</canView>
                    <canEdit>true</canEdit>
                    <canDelete>false</canDelete>
                    <allowedToExecute>false</allowedToExecute>
                    <canExecute>false</canExecute>
                    <cantExecuteReason>Not authorized</cantExecuteReason>
                    <allowedToCreateVersion>false</allowedToCreateVersion>
                    <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
                </operations>
                <creatorDisplayName>Administrator User</creatorDisplayName>
                <creatorGravatarUrl></creatorGravatarUrl>
                <planBranchName>PLAN12</planBranchName>
                <ageZeroPoint>2018-09-25T13:29:33.482Z</ageZeroPoint>
            </deploymentVersion>
            <deploymentVersionName>release-2</deploymentVersionName>
            <id>2</id>
            <deploymentState>SUCCESS</deploymentState>
            <lifeCycleState>FINISHED</lifeCycleState>
            <startedDate>2018-09-25T13:29:33.482Z</startedDate>
            <queuedDate>2018-09-25T13:29:33.482Z</queuedDate>
            <executedDate>2018-09-25T13:29:33.482Z</executedDate>
            <finishedDate>2018-09-25T13:29:33.482Z</finishedDate>
            <reasonSummary>Manual build</reasonSummary>
            <key>
                <key>123-123-2</key>
                <entityKey>
                    <key>123-123</key>
                </entityKey>
                <resultNumber>2</resultNumber>
            </key>
            <operations>
                <canView>true</canView>
                <canEdit>true</canEdit>
                <canDelete>false</canDelete>
                <allowedToExecute>false</allowedToExecute>
                <canExecute>false</canExecute>
                <cantExecuteReason>Not authorized</cantExecuteReason>
                <allowedToCreateVersion>false</allowedToCreateVersion>
                <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
            </operations>
        </results>
    </restDeploymentResultList>
    

    XML Schema

    Source:

  • 403 [expand]

    Returns when user don't have VIEW permission for environment

  • 404 [expand]

    Returns when environment not found

/deploy/environment/{environmentId}/agent-assignment

resource-wide template parameters
parameter value description

environmentId

long

environment id

Methods

GET

Provide list of agents/images assigned to given environment.

available response representations:

  • 403 [expand]

    If the user has no permissions for updating an agent assignment, which translates into no WRITE permissions to edit the configuration of the environment

  • 404 [expand]

    If the environment id is not found

POST

Add agent assignment for environment. agentAssignmentKey is a map with one key-value: name - agentAssignmentKey. agentAssignmentKey is parsed by {@link ExecutorKey}.

acceptable request representations:

available response representations:

  • 400 [expand]

    If validation fails

  • 403 [expand]

    If the user has no permissions for updating an agent assignment, which translates into no WRITE permissions to edit the configuration of the environment

  • 404 [expand]

    If the environment id is not found

/deploy/environment/{environmentId}/possible-agent-assignment?searchTerm

resource-wide template parameters
parameter value description

environmentId

long

environment id

Methods

GET

Provide list of agents/images which can be dedicated for given environment.

request query parameters
parameter value description

searchTerm

string

part of the agent or image name to filter response. Use empty value to receive all agents/images.

available response representations:

  • 403 [expand]

    If the user has no permissions for updating an agent assignment, which translates into no WRITE permissions to edit the configuration of the environment

  • 404 [expand]

    If the environment id is not found

/deploy/environment/{environmentId}/agent-assignment/{executorKey}

resource-wide template parameters
parameter value description

environmentId

long

environment id

executorKey

string

key is parsed by {@link ExecutorKey}

Methods

DELETE

Remove agent/image from list of dedicated executors for given environment.

available response representations:

  • 400 [expand]

    If validation fails

  • 204 [expand]

    On successful removal of agent assignment

  • 403 [expand]

    If the user has no permissions for updating an agent assignment, which translates into no WRITE permissions to edit the configuration of the environment

  • 404 [expand]

    If the environment id is not found

/deploy/environment/{environmentId}/docker

resource-wide template parameters
parameter value description

environmentId

long

Methods

GET

Retrieves Docker configuration for given environment.

available response representations:

  • 200 [expand]

    Returns Docker Pipeline configuration for given environment

  • 400 [expand]

    If validation fails

  • 403 [expand]

    If the user has no edit permissions

  • 404 [expand]

    If the environment id is not found

PUT

Saves Docker configuration for given environment.

available response representations:

  • 200 [expand]

    Returns Docker Pipeline configuration for given environment

  • 400 [expand]

    If validation fails

  • 403 [expand]

    If the user has no edit permissions

  • 404 [expand]

    If the environment id is not found

/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:

/deploy/issue-status

Methods

/deploy/issue-status/{issueKey}

resource-wide template parameters
parameter value description

issueKey

string

JIRA issue key. Mandatory

Methods

GET

Get deployment project environments and versions associated with JIRA issue

available response representations:

  • 200 - application/json (restDeploymentProjectStatusForJiraIssue) [expand]
    XML Schema

    Source:

  • 404 [expand]

    deployment project not found

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

resource-wide template parameters
parameter value description

issueKey

string

JIRA issue key. Mandatory

deploymentProjectId

long

deployment project id

Methods

GET

Get deployment project environments and versions associated with JIRA issue

available response representations:

  • 200 - application/json (restDeploymentProjectStatusForJiraIssue) [expand]
    XML Schema

    Source:

  • 404 [expand]

    deployment project not found

/admin/users?filter

REST resource to manage users in Bamboo.

Methods

GET

Retrieve a page of users. The authenticated user must have restricted administrative permission or higher to use this resource.

request query parameters
parameter value description

filter

string

Default:

available response representations:

  • 200 - application/json (page) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restPageModel>
        <start>0</start>
        <limit>10</limit>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
    </restPageModel>
    

    A page of users.

    XML Schema

    Source:

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

POST

Create a new user. The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 400 - application/json [expand]

    User couldn't be created. The response will hold additional information.

  • 204 [expand]

    When user has been created.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

/admin/users/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

The name identifying the user to delete.

Methods

DELETE

Deletes the specified user, removing them from the system. The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 400 [expand]

    User couldn't be deleted. The response will hold additional information.

  • 204 [expand]

    When user has been deleted successfully or user does not exist.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

/admin/users/rename

Methods

PUT

Renames specified user The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 400 [expand]

    When the user couldn't be renamed. The response will hold additional information.

  • 204 [expand]

    When user has been renamed successfully.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

  • 404 [expand]

    The specified user does not exist.

/admin/users/credentials

Methods

PUT

Change password of specified user The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 400 [expand]

    When the password couldn't be changed. The response will hold additional information.

  • 204 [expand]

    Users password has been changed.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

  • 404 [expand]

    The specified user does not exist.

/admin/users/{name : (.+)?}/groups

resource-wide template parameters
parameter value description

name

string

Methods

POST

Add a user to multiple groups. The list of groups should be passed as request body. The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 400 [expand]

    When user couldn't be added to one or more groups. The response will hold additional information.

  • 204 [expand]

    The user has been added to all specified groups.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

  • 404 [expand]

    The specified user or groups do not exist.

DELETE

Remove a user from multiple groups. The list of groups should be passed as request body. The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 400 [expand]

    When user couldn't be removed from one or more groups. The response will hold additional information.

  • 204 [expand]

    The user has been removed from all specified groups.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

  • 404 [expand]

    The specified user or groups do not exist.

/admin/users/{name : (.+)?}/assigned-groups?filter

resource-wide template parameters
parameter value description

name

string

Methods

GET

Retrieves a list of groups to which the user belongs. The authenticated user must have restricted administrative permission or higher to use this resource.

request query parameters
parameter value description

filter

string

Default:

available response representations:

  • 200 [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restPageModel>
        <start>0</start>
        <limit>10</limit>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
    </restPageModel>
    

    A page of users.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

  • 404 [expand]

    The specified user do not exist.

/admin/users/{name : (.+)?}/unassigned-groups?filter

resource-wide template parameters
parameter value description

name

string

Methods

GET

Retrieves a list of groups to which the user does not belong. The authenticated user must have restricted administrative permission or higher to use this resource.

request query parameters
parameter value description

filter

string

Default:

available response representations:

  • 200 [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restPageModel>
        <start>0</start>
        <limit>10</limit>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
    </restPageModel>
    

    A page of users.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

  • 404 [expand]

    The specified user do not exist.

/admin/users/{name : (.+)?}/unassigned-aliases?filter

resource-wide template parameters
parameter value description

name

string

Methods

GET

Retrieves a list of unlinked aliases to which the user does not belong. The authenticated user must have restricted administrative permission or higher to use this resource.

request query parameters
parameter value description

filter

string

Default:

available response representations:

  • 200 [expand]

    A page of aliases.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

  • 404 [expand]

    The specified user do not exist.

/admin/users/{name : (.+)?}/alias

resource-wide template parameters
parameter value description

name

string

The name identifying the user to delete.

Methods

GET

Retrieve a page of aliases. The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 200 - application/json (page) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restPageModel>
        <start>0</start>
        <limit>10</limit>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
    </restPageModel>
    

    A page of aliases.

    XML Schema

    Source:

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

POST

Link existing unlined alias or create the new one. The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 400 - application/json [expand]

    Alias couldn't be created. The response will hold additional information.

  • 204 [expand]

    When alias has been created.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

DELETE

Unlink the specified alias from user, removing them from the system. The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 400 [expand]

    User couldn't be deleted. The response will hold additional information.

  • 204 [expand]

    When alias has been unlinked successfully or given user doesn't have this alias.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

  • 404 [expand]

    The specified user does not exist.

/info

Methods

GET

available response representations:

  • application/xml (info) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="info" type="restInfo"/><xs:element name="info" type="restInfo"/>
  • application/json (info) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="info" type="restInfo"/><xs:element name="info" type="restInfo"/>

/admin/groups

REST resource to manage groups in Bamboo.

Methods

POST

Create a new group. The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 400 [expand]

    When group couldn't be created. The response will hold additional information.

  • 204 [expand]

    When group has been created.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

GET

Retrieve a paginated list of groups. The authenticated user must have restricted administrative permission or higher to use this resource.

request query parameters
parameter value description

filter

string

Default:

available response representations:

  • 200 - application/json (page) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restPageModel>
        <start>0</start>
        <limit>10</limit>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
    </restPageModel>
    

    A page of groups.

    XML Schema

    Source:

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

/admin/groups/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

the name identifying the group to delete

Methods

DELETE

Deletes the specified group, removing it from the system. The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 400 [expand]

    When group couldn't be deleted. The response will hold additional information.

  • 204 [expand]

    When group was deleted successfully.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

  • 404 [expand]

    The specified group does not exist.

/admin/groups/{name : (.+)?}/add-users

resource-wide template parameters
parameter value description

name

string

Methods

POST

Add multiple users to a group. The list of usernames should be passed as request body. The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 400 [expand]

    When the users couldn't be added to the group. The response will hold additional information.

  • 204 [expand]

    All the users were added to the group

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

  • 404 [expand]

    The specified group or users do not exist.

/admin/groups/{name : (.+)?}/remove-users

resource-wide template parameters
parameter value description

name

string

Methods

DELETE

Remove multiple users from a group. The list of usernames should be passed as request body. The authenticated user must have restricted administrative permission or higher to use this resource.

available response representations:

  • 400 [expand]

    When the users couldn't be removed from the group. The response will hold additional information.

  • 204 [expand]

    All the users were removed from the group

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

  • 404 [expand]

    The specified group or users do not exist.

/admin/groups/{name : (.+)?}/more-members?filter

resource-wide template parameters
parameter value description

name

string

Methods

GET

Retrieves a list of users that are members of a specified group. The authenticated user must have restricted administrative permission or higher to use this resource.

request query parameters
parameter value description

filter

string

Default:

available response representations:

  • 200 [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restPageModel>
        <start>0</start>
        <limit>10</limit>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
    </restPageModel>
    

    A page of users.

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

  • 404 [expand]

    The specified group or users do not exist.

/admin/groups/{name : (.+)?}/more-non-members?filter

resource-wide template parameters
parameter value description

name

string

Methods

GET

Retrieves a list of users that are not members of a specified group. The authenticated user must have restricted administrative permission or higher to use this resource.

request query parameters
parameter value description

filter

string

Default:

available response representations:

  • 200 (page) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restPageModel>
        <start>0</start>
        <limit>10</limit>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
        <results xsi:type="abstractRestModel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
    </restPageModel>
    

    A page of users.

    XML Schema

    Source:

  • 403 [expand]

    The currently authenticated user does not have sufficient permissions.

/agent/assignment?executorType&executorId

Methods

GET

request query parameters
parameter value description

executorType

string

executorId

long

available response representations:

  • application/json (dedicatedAgent) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="dedicatedAgent" type="restDedicatedAgent"/><xs:element name="dedicatedAgent" type="restDedicatedAgent"/>

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

should be AGENT or IMAGE

executorId

long

executor id

assignmentType

string

should be PROJECT, PLAN, JOB, ENVIRONMENT

entityId

long

entity id

available response representations:

  • 400 - application/json [expand]

    when can't parse executorType or executableType

  • 401 - application/json [expand]

    A response with code HTTP 401 indicates that the calling user had insufficient permissions for the request.

  • 204 [expand]

    successful removal of agent assignment

/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]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="searchResults" type="searchResultsList"/><xs:element name="searchResults" type="searchResultsList"/>

/permissions/plan

REST endpoint to manage user/group plan permissions in Bamboo.

Methods

/permissions/plan/{key}/users?name

resource-wide template parameters
parameter value description

key

string

plan entity key

Methods

GET

Retrieve a list of users with their explicit permissions to given resource. The list can be filtered by some attributes. This resource is paged and returns a single page of results.

request query parameters
parameter value description

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/plan/{key}/users/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

username of the affected user

key

string

plan entity key

Methods

PUT

Grants plan permissions to a given user.

available response representations:

  • 400 [expand]

    If 'username' user doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If user already had requested permissions and permission state hasn't been changed.

DELETE

Revokes plan permissions from a given user.

available response representations:

  • 400 [expand]

    If the 'username' user doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If user already lacked requested permissions and permission state hasn't been changed.

/permissions/plan/{key}/available-users?name

resource-wide template parameters
parameter value description

key

string

plan entity key

Methods

GET

Returns list of users which weren't granted explicitly any plan permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/plan/{key}/groups?name

resource-wide template parameters
parameter value description

key

string

plan entity key

Methods

GET

Retrieve a list of groups with their plan permissions. The list can be filtered by some attributes. This resource is paged returns a single page of results.

request query parameters
parameter value description

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/plan/{key}/groups/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

affected group

key

string

plan entity key

Methods

PUT

Grants plan permissions to a given group.

available response representations:

  • 400 [expand]

    If group doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If group already had requested permissions and permission state hasn't been changed.

DELETE

Revokes plan permissions from a given group.

available response representations:

  • 400 [expand]

    If group doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If group already lacked requested permissions and permission state hasn't been changed.

/permissions/plan/{key}/available-groups?name

resource-wide template parameters
parameter value description

key

string

plan entity key

Methods

GET

Returns list of groups which weren't granted explicitly any plan permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/plan/{key}/roles

resource-wide template parameters
parameter value description

key

string

plan entity key

Methods

GET

Retrieve a list of roles with their plan permissions. This resource is paged returns a single page of results, although only 2 roles are supported: LOGGED IN users, ANONYMOUS users

available response representations:

  • 200 [expand]

    Return single page of roles with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/plan/{key}/roles/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

affected role

key

string

plan entity key

Methods

PUT

Grants plan permissions to a given role.

available response representations:

  • 400 [expand]

    If role doesn't exist or one of the requested permission isn't supported for given role. Anonymous role supports only VIEW permission.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If role already had requested permissions and permission state hasn't been changed.

DELETE

Revokes plan permissions from a given role.

available response representations:

  • 400 [expand]

    If role doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If role already lacked requested permissions and permission state hasn't been changed.

/deploy/project

Methods

PUT

Create deployment project.

acceptable request representations:

  • application/json (createDeploymentProjectRequest) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <createDeploymentProjectRequest>
        <name>Test deployment</name>
        <planKey>
            <key>PROJ-PLAN</key>
        </planKey>
        <description>Project description</description>
    </createDeploymentProjectRequest>
    

    XML Schema

    Source: xsd0.xsd

    <xs:element name="createDeploymentProjectRequest" type="restCreateDeploymentProjectRequest"/><xs:element name="createDeploymentProjectRequest" type="restCreateDeploymentProjectRequest"/>

available response representations:

  • 200 - application/json (restDeploymentProject) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <deploymentProject>
        <id>12</id>
        <oid>21ayer</oid>
        <key>
            <key>213123213</key>
        </key>
        <name>Test deployment</name>
        <planKey>
            <key>PROJ-PLAN</key>
        </planKey>
        <description>Project description</description>
        <environments>
            <id>12</id>
            <key>
                <key>1111</key>
            </key>
            <name>Dev</name>
            <description>Dev environment</description>
            <deploymentProjectId>12</deploymentProjectId>
            <operations>
                <canView>true</canView>
                <canEdit>true</canEdit>
                <canDelete>false</canDelete>
                <allowedToExecute>false</allowedToExecute>
                <canExecute>false</canExecute>
                <cantExecuteReason>Not authorized</cantExecuteReason>
                <allowedToCreateVersion>false</allowedToCreateVersion>
                <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
            </operations>
            <position>0</position>
            <configurationState>TASKED</configurationState>
        </environments>
        <environments>
            <id>17</id>
            <key>
                <key>1111</key>
            </key>
            <name>QA</name>
            <description>QA environment</description>
            <deploymentProjectId>12</deploymentProjectId>
            <operations>
                <canView>true</canView>
                <canEdit>true</canEdit>
                <canDelete>false</canDelete>
                <allowedToExecute>false</allowedToExecute>
                <canExecute>false</canExecute>
                <cantExecuteReason>Not authorized</cantExecuteReason>
                <allowedToCreateVersion>false</allowedToCreateVersion>
                <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
            </operations>
            <position>1</position>
            <configurationState>TASKED</configurationState>
        </environments>
        <operations>
            <canView>true</canView>
            <canEdit>true</canEdit>
            <canDelete>false</canDelete>
            <allowedToExecute>false</allowedToExecute>
            <canExecute>false</canExecute>
            <cantExecuteReason>Not authorized</cantExecuteReason>
            <allowedToCreateVersion>false</allowedToCreateVersion>
            <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
        </operations>
    </deploymentProject>
    

    Created deployment project

    XML Schema

    Source: xsd0.xsd

    <xs:complexType name="restDeploymentProject">
        <xs:sequence>
          <xs:element name="id" type="xs:long"/>
          <xs:element name="oid" type="xs:string" minOccurs="0"/>
          <xs:element ref="key" minOccurs="0"/>
          <xs:element name="name" type="xs:string" minOccurs="0"/>
          <xs:element name="planKey" type="restKey" minOccurs="0"/>
          <xs:element name="description" type="xs:string" minOccurs="0"/>
          <xs:element name="environments" type="restEnvironment" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element ref="operations" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType><xs:complexType name="restDeploymentProject">
        <xs:sequence>
          <xs:element name="id" type="xs:long"/>
          <xs:element name="oid" type="xs:string" minOccurs="0"/>
          <xs:element ref="key" minOccurs="0"/>
          <xs:element name="name" type="xs:string" minOccurs="0"/>
          <xs:element name="planKey" type="restKey" minOccurs="0"/>
          <xs:element name="description" type="xs:string" minOccurs="0"/>
          <xs:element name="environments" type="restEnvironment" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element ref="operations" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType>
  • 400 - application/json (restErrorCollection) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <errors>
        <errors>Can't create deployment project because CreateDeploymentProjectRequest is empty</errors>
        <fieldErrors/>
    </errors>
    

    Validation error

    XML Schema

    Source:

/deploy/project/{deploymentProjectId}

resource-wide template parameters
parameter value description

deploymentProjectId

long

deployment project id

Methods

GET

Find deployment project by id.

available response representations:

  • 200 - application/json (restDeploymentProject) [expand]

    return deployment project

    XML Schema

    Source: xsd0.xsd

    <xs:complexType name="restDeploymentProject">
        <xs:sequence>
          <xs:element name="id" type="xs:long"/>
          <xs:element name="oid" type="xs:string" minOccurs="0"/>
          <xs:element ref="key" minOccurs="0"/>
          <xs:element name="name" type="xs:string" minOccurs="0"/>
          <xs:element name="planKey" type="restKey" minOccurs="0"/>
          <xs:element name="description" type="xs:string" minOccurs="0"/>
          <xs:element name="environments" type="restEnvironment" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element ref="operations" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType><xs:complexType name="restDeploymentProject">
        <xs:sequence>
          <xs:element name="id" type="xs:long"/>
          <xs:element name="oid" type="xs:string" minOccurs="0"/>
          <xs:element ref="key" minOccurs="0"/>
          <xs:element name="name" type="xs:string" minOccurs="0"/>
          <xs:element name="planKey" type="restKey" minOccurs="0"/>
          <xs:element name="description" type="xs:string" minOccurs="0"/>
          <xs:element name="environments" type="restEnvironment" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element ref="operations" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType>
  • 404 [expand]

    Can't find deployment project by deploymentProjectId

POST

Update deployment project.

acceptable request representations:

  • application/json (updateDeploymentProjectRequest) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <updateDeploymentProjectRequest>
        <name>Test deployment</name>
        <planKey>
            <key>PROJ-PLAN</key>
        </planKey>
        <description>Project description</description>
    </updateDeploymentProjectRequest>
    

    XML Schema

    Source: xsd0.xsd

    <xs:element name="updateDeploymentProjectRequest" type="restUpdateDeploymentProjectRequest"/><xs:element name="updateDeploymentProjectRequest" type="restUpdateDeploymentProjectRequest"/>

available response representations:

  • 200 - application/json (restDeploymentProject) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <deploymentProject>
        <id>12</id>
        <oid>21ayer</oid>
        <key>
            <key>213123213</key>
        </key>
        <name>Test deployment</name>
        <planKey>
            <key>PROJ-PLAN</key>
        </planKey>
        <description>Project description</description>
        <environments>
            <id>12</id>
            <key>
                <key>1111</key>
            </key>
            <name>Dev</name>
            <description>Dev environment</description>
            <deploymentProjectId>12</deploymentProjectId>
            <operations>
                <canView>true</canView>
                <canEdit>true</canEdit>
                <canDelete>false</canDelete>
                <allowedToExecute>false</allowedToExecute>
                <canExecute>false</canExecute>
                <cantExecuteReason>Not authorized</cantExecuteReason>
                <allowedToCreateVersion>false</allowedToCreateVersion>
                <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
            </operations>
            <position>0</position>
            <configurationState>TASKED</configurationState>
        </environments>
        <environments>
            <id>17</id>
            <key>
                <key>1111</key>
            </key>
            <name>QA</name>
            <description>QA environment</description>
            <deploymentProjectId>12</deploymentProjectId>
            <operations>
                <canView>true</canView>
                <canEdit>true</canEdit>
                <canDelete>false</canDelete>
                <allowedToExecute>false</allowedToExecute>
                <canExecute>false</canExecute>
                <cantExecuteReason>Not authorized</cantExecuteReason>
                <allowedToCreateVersion>false</allowedToCreateVersion>
                <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
            </operations>
            <position>1</position>
            <configurationState>TASKED</configurationState>
        </environments>
        <operations>
            <canView>true</canView>
            <canEdit>true</canEdit>
            <canDelete>false</canDelete>
            <allowedToExecute>false</allowedToExecute>
            <canExecute>false</canExecute>
            <cantExecuteReason>Not authorized</cantExecuteReason>
            <allowedToCreateVersion>false</allowedToCreateVersion>
            <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
        </operations>
    </deploymentProject>
    

    return deployment project

    XML Schema

    Source: xsd0.xsd

    <xs:complexType name="restDeploymentProject">
        <xs:sequence>
          <xs:element name="id" type="xs:long"/>
          <xs:element name="oid" type="xs:string" minOccurs="0"/>
          <xs:element ref="key" minOccurs="0"/>
          <xs:element name="name" type="xs:string" minOccurs="0"/>
          <xs:element name="planKey" type="restKey" minOccurs="0"/>
          <xs:element name="description" type="xs:string" minOccurs="0"/>
          <xs:element name="environments" type="restEnvironment" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element ref="operations" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType><xs:complexType name="restDeploymentProject">
        <xs:sequence>
          <xs:element name="id" type="xs:long"/>
          <xs:element name="oid" type="xs:string" minOccurs="0"/>
          <xs:element ref="key" minOccurs="0"/>
          <xs:element name="name" type="xs:string" minOccurs="0"/>
          <xs:element name="planKey" type="restKey" minOccurs="0"/>
          <xs:element name="description" type="xs:string" minOccurs="0"/>
          <xs:element name="environments" type="restEnvironment" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element ref="operations" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType>
  • 400 - application/json [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <errors>
        <errors>No deployment project was found for the given ID 123</errors>
        <fieldErrors/>
    </errors>
    

    Validation error

  • 404 [expand]

    Can't find deployment project by deploymentProjectId

/deploy/project/{deploymentProjectId}/version

resource-wide template parameters
parameter value description

deploymentProjectId

long

id of deployment project

Methods

POST

Create deployment version for given deployment project.

acceptable request representations:

  • application/json (restCreateVersionRequest) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restCreateVersionRequest>
        <planResultKey>PRJ-PLN-2</planResultKey>
        <name>version1</name>
        <nextVersionName>version2</nextVersionName>
    </restCreateVersionRequest>
    

    XML Schema

    Source: xsd0.xsd

    <xs:element name="restCreateVersionRequest" type="restCreateVersionRequest"/><xs:element name="restCreateVersionRequest" type="restCreateVersionRequest"/>

available response representations:

  • 200 - application/json (restDeploymentVersion) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <version>
        <id>15</id>
        <name>version1</name>
        <creationDate>2018-09-25T13:29:33.735Z</creationDate>
        <creatorUserName>Administrator User</creatorUserName>
        <versionStatus>
            <id>1</id>
            <userName>admin</userName>
            <displayName>Approved</displayName>
            <gravatarUrl></gravatarUrl>
            <creationDate>2018-09-25T13:29:33.735Z</creationDate>
            <versionState>APPROVED</versionState>
        </versionStatus>
        <operations>
            <canView>true</canView>
            <canEdit>true</canEdit>
            <canDelete>false</canDelete>
            <allowedToExecute>false</allowedToExecute>
            <canExecute>false</canExecute>
            <cantExecuteReason>Not authorized</cantExecuteReason>
            <allowedToCreateVersion>false</allowedToCreateVersion>
            <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
        </operations>
        <creatorDisplayName>Administrator User</creatorDisplayName>
        <creatorGravatarUrl></creatorGravatarUrl>
        <planBranchName>PLAN12</planBranchName>
        <ageZeroPoint>2018-09-25T13:29:33.735Z</ageZeroPoint>
    </version>
    

    XML Schema

    Source: xsd0.xsd

    <xs:complexType name="restDeploymentVersion">
        <xs:sequence>
          <xs:element name="id" type="xs:long"/>
          <xs:element name="name" type="xs:string" minOccurs="0"/>
          <xs:element name="creationDate" type="xs:dateTime" minOccurs="0"/>
          <xs:element name="creatorUserName" type="xs:string" minOccurs="0"/>
          <xs:element name="items" type="restDeploymentVersionItem" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="versionStatus" type="restDeploymentVersionStatus" minOccurs="0"/>
          <xs:element ref="operations" minOccurs="0"/>
          <xs:element name="creatorDisplayName" type="xs:string" minOccurs="0"/>
          <xs:element name="creatorGravatarUrl" type="xs:string" minOccurs="0"/>
          <xs:element name="planBranchName" type="xs:string" minOccurs="0"/>
          <xs:element name="ageZeroPoint" type="xs:dateTime" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType><xs:complexType name="restDeploymentVersion">
        <xs:sequence>
          <xs:element name="id" type="xs:long"/>
          <xs:element name="name" type="xs:string" minOccurs="0"/>
          <xs:element name="creationDate" type="xs:dateTime" minOccurs="0"/>
          <xs:element name="creatorUserName" type="xs:string" minOccurs="0"/>
          <xs:element name="items" type="restDeploymentVersionItem" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="versionStatus" type="restDeploymentVersionStatus" minOccurs="0"/>
          <xs:element ref="operations" minOccurs="0"/>
          <xs:element name="creatorDisplayName" type="xs:string" minOccurs="0"/>
          <xs:element name="creatorGravatarUrl" type="xs:string" minOccurs="0"/>
          <xs:element name="planBranchName" type="xs:string" minOccurs="0"/>
          <xs:element name="ageZeroPoint" type="xs:dateTime" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType>
  • 400 - application/json (restErrorCollection) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <errors>
        <fieldErrors>
            <entry>
                <key>versionName</key>
                <value/>
            </entry>
        </fieldErrors>
    </errors>
    

    Returns when validation error occurred

    XML Schema

    Source:

  • 401 [expand]

    Returns for anonymous access

  • 403 [expand]

    Returns when user don't have permissions to create version in deployment project

  • 404 [expand]

    Can't find deployment project by deploymentProjectId

/deploy/project/forPlan?planKey

Methods

GET

Get list of deployment projects for build plan.

request query parameters
parameter value description

planKey

string

plan key. Required

available response representations:

  • 200 - application/json (restLinkedDeploymentProjectList) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restLinkedDeploymentProject>
        <id>12</id>
        <name>Deployment project 1</name>
        <description>Deployment project 1 description</description>
    </restLinkedDeploymentProject>
    

    list of linked deployment projects

    XML Schema

    Source:

  • 400 - application/json (restErrorCollection) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <errors>
        <errors>Please provide a valid plan key</errors>
        <fieldErrors/>
    </errors>
    

    when plan key is empty or plan don't found

    XML Schema

    Source:

/deploy/project/{deploymentProjectId}/repository

resource-wide template parameters
parameter value description

deploymentProjectId

long

Methods

GET

Fetch list of repositories which granted to create/edit environment in given deployment project by Repository stored Bamboo Specs. Returns json array: [{"id":"123", "name":"repo1", "url":"http://localhost:8085/admin/configureLinkedRepositories.action?repositoryId=123"}]

available response representations:

  • 200 [expand]

    The page object with list of repositories.

  • 403 [expand]

    Returned when user has no Administration permission to project

  • 404 [expand]

    Returned when specified project does not exist

POST

Grant permission to create/edit plan in given deployment project by Bamboo Specs from given repository.

acceptable request representations:

  • application/json (restIdContainer) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="restIdContainer" type="restIdContainer"/><xs:element name="restIdContainer" type="restIdContainer"/>

available response representations:

  • 201 [expand]

    added repository entity.

  • 400 [expand]

    Returned when idContainer is empty or null

  • 403 [expand]

    Returned when user has no Administration permission to project

  • 404 [expand]

    Returned when specified project does not exist or repository not found by id

/deploy/project/{deploymentProjectId}/repository/{repositoryId}

resource-wide template parameters
parameter value description

repositoryId

long

linked repository root id

deploymentProjectId

long

project key

Methods

DELETE

Remove approval to create plans in given deployment project by given repository

available response representations:

  • 204 [expand]

    When successfully removed link between project and repository.

  • 403 [expand]

    Returned when user has no Administration permission to project

  • 404 [expand]

    Returned when specified project or repository does not exist

/deploy/project/{deploymentProjectId}/repository/search?searchTerm

resource-wide template parameters
parameter value description

deploymentProjectId

long

Methods

GET

Search for linked repositories which can be granted to create/modify environment by Repository stored Bamboo Specs in given deployment project.

request query parameters
parameter value description

searchTerm

string

available response representations:

  • 200 [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restRepositoryList start-index="0" max-result="1" size="2">
        <searchResults>
            <id>123</id>
            <name>linked repository 1</name>
            <url>http://localhost:8085/admin/configureLinkedRepositories.action?repositoryId=123</url>
            <rssEnabled>true</rssEnabled>
        </searchResults>
        <searchResults>
            <id>321</id>
            <name>linked repository 2</name>
            <url>http://localhost:8085/admin/configureLinkedRepositories.action?repositoryId=321</url>
            <rssEnabled>true</rssEnabled>
        </searchResults>
    </restRepositoryList>
    

    The page object with list of repositories.

  • 403 [expand]

    Returned when user has no Administration permission to deployment project

  • 404 [expand]

    Returned when specified deployment project does not exist

/deploy/project/all

Methods

GET

Find all deployment projects with environments. Returns only deployment projects and environments visible for user.

available response representations:

  • 200 - application/json (deploymentProjectsList) [expand]

    List of deployment projects with environments

    XML Schema

    Source:

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

resource-wide template parameters
parameter value description

deploymentProjectId

long

deployment project id

Methods

GET

Get list of deployment versions by deployment project id

request query parameters
parameter value description

branchKey

string

plan branch key. Can be empty if default branch is required

available response representations:

  • 200 - application/json (restDeploymentVersionList) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <deploymentVersions start-index="0" max-result="2" size="2">
        <versions>
            <id>15</id>
            <name>version1</name>
            <creationDate>2018-09-25T13:29:33.741Z</creationDate>
            <creatorUserName>Administrator User</creatorUserName>
            <versionStatus>
                <id>1</id>
                <userName>admin</userName>
                <displayName>Approved</displayName>
                <gravatarUrl></gravatarUrl>
                <creationDate>2018-09-25T13:29:33.741Z</creationDate>
                <versionState>APPROVED</versionState>
            </versionStatus>
            <operations>
                <canView>true</canView>
                <canEdit>true</canEdit>
                <canDelete>false</canDelete>
                <allowedToExecute>false</allowedToExecute>
                <canExecute>false</canExecute>
                <cantExecuteReason>Not authorized</cantExecuteReason>
                <allowedToCreateVersion>false</allowedToCreateVersion>
                <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
            </operations>
            <creatorDisplayName>Administrator User</creatorDisplayName>
            <creatorGravatarUrl></creatorGravatarUrl>
            <planBranchName>PLAN12</planBranchName>
            <ageZeroPoint>2018-09-25T13:29:33.741Z</ageZeroPoint>
        </versions>
        <versions>
            <id>15</id>
            <name>version1</name>
            <creationDate>2018-09-25T13:29:33.741Z</creationDate>
            <creatorUserName>Administrator User</creatorUserName>
            <versionStatus>
                <id>1</id>
                <userName>admin</userName>
                <displayName>Approved</displayName>
                <gravatarUrl></gravatarUrl>
                <creationDate>2018-09-25T13:29:33.741Z</creationDate>
                <versionState>APPROVED</versionState>
            </versionStatus>
            <operations>
                <canView>true</canView>
                <canEdit>true</canEdit>
                <canDelete>false</canDelete>
                <allowedToExecute>false</allowedToExecute>
                <canExecute>false</canExecute>
                <cantExecuteReason>Not authorized</cantExecuteReason>
                <allowedToCreateVersion>false</allowedToCreateVersion>
                <allowedToSetVersionStatus>false</allowedToSetVersionStatus>
            </operations>
            <creatorDisplayName>Administrator User</creatorDisplayName>
            <creatorGravatarUrl></creatorGravatarUrl>
            <planBranchName>PLAN12</planBranchName>
            <ageZeroPoint>2018-09-25T13:29:33.741Z</ageZeroPoint>
        </versions>
    </deploymentVersions>
    

    deployment project versions

    XML Schema

    Source:

  • 400 [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <errors>
        <errors>Please provide a valid planBranchKey</errors>
        <fieldErrors/>
    </errors>
    

    Validation error during deployment project update

  • 404 [expand]

    Can't find deployment project by deploymentProjectId

/permissions/project

REST endpoint to manage user/group project permissions in Bamboo.

Methods

/permissions/project/{key}/users?name

resource-wide template parameters
parameter value description

key

string

project entity key

Methods

GET

Retrieve a list of users with their explicit permissions to given resource. The list can be filtered by some attributes. This resource is paged and returns a single page of results.

request query parameters
parameter value description

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/project/{key}/users/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

username of the affected user

key

string

project entity key

Methods

PUT

Grants project permissions to a given user.

available response representations:

  • 400 [expand]

    If 'username' user doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If user already had requested permissions and permission state hasn't been changed.

DELETE

Revokes project permissions from a given user.

available response representations:

  • 400 [expand]

    If the 'username' user doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If user already lacked requested permissions and permission state hasn't been changed.

/permissions/project/{key}/available-users?name

resource-wide template parameters
parameter value description

key

string

project entity key

Methods

GET

Returns list of users which weren't granted explicitly any project permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/project/{key}/groups?name

resource-wide template parameters
parameter value description

key

string

project entity key

Methods

GET

Retrieve a list of groups with their project permissions. The list can be filtered by some attributes. This resource is paged returns a single page of results.

request query parameters
parameter value description

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/project/{key}/groups/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

affected group

key

string

project entity key

Methods

PUT

Grants project permissions to a given group.

available response representations:

  • 400 [expand]

    If group doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If group already had requested permissions and permission state hasn't been changed.

DELETE

Revokes project permissions from a given group.

available response representations:

  • 400 [expand]

    If group doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If group already lacked requested permissions and permission state hasn't been changed.

/permissions/project/{key}/available-groups?name

resource-wide template parameters
parameter value description

key

string

project entity key

Methods

GET

Returns list of groups which weren't granted explicitly any project permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/project/{key}/roles

resource-wide template parameters
parameter value description

key

string

project entity key

Methods

GET

Retrieve a list of roles with their project permissions. This resource is paged returns a single page of results, although only LOGGED IN users role is supported

available response representations:

  • 200 [expand]

    Return single page of roles with their permissions

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

/permissions/project/{key}/roles/{name : (.+)?}

resource-wide template parameters
parameter value description

name

string

affected role

key

string

project entity key

Methods

PUT

Grants project permissions to a given role.

available response representations:

  • 400 [expand]

    If role doesn't exist or one of the requested permission isn't supported for given role.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If role already had requested permissions and permission state hasn't been changed.

DELETE

Revokes project permissions from a given role.

available response representations:

  • 400 [expand]

    If role doesn't exist.

  • 401 [expand]

    If the user lacks effective admin permissions for given entity.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If role already lacked requested permissions and permission state hasn't been changed.

/quickFilter

Methods

GET

Obtain a list of quick filters defined for this Bamboo instance.

available response representations:

  • 200 - application/json [expand]

    List of quick filters. Each entity will contain only basic configuration, excluding e.g. quick filter's rules.

POST

Create a new quick filter with basic configuration, e.g. name or position on list. This method does not allow to configure quick filter's rules.

acceptable request representations:

  • application/json (quickFilter) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <quickFilter>
        <name>Integration Tests</name>
    </quickFilter>
    

    XML Schema

    Source: xsd0.xsd

    <xs:element name="quickFilter" type="restQuickFilter"/><xs:element name="quickFilter" type="restQuickFilter"/>

available response representations:

  • 200 - application/json [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <quickFilter>
        <id>100623</id>
        <name>Integration Tests</name>
        <position>3</position>
        <hasRules>false</hasRules>
    </quickFilter>
    

    Returned when quick filter was created successfully. Response will contain Quick Filter definition with assigned ID.

  • 400 - application/json [expand]

    When any validation errors occur. Response will contain all error messages.

/quickFilter/{id}

resource-wide template parameters
parameter value description

id

long

Methods

GET

Get a single quick filter by ID.

available response representations:

  • 200 - application/json [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <quickFilter>
        <id>100623</id>
        <name>Integration Tests</name>
        <position>3</position>
        <hasRules>false</hasRules>
    </quickFilter>
    

    Single quick filter data. Will contain only basic configuration, excluding e.g. quick filter's rules.

  • 400 - application/json [expand]

    Sent when quick filter was not found with the given ID.

PUT

Update quick filter's basic configuration, e.g. name or position on list. This method does not allow to configure quick filter's rules.

acceptable request representations:

  • application/json (quickFilter) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <quickFilter>
        <id>100623</id>
        <name>Integration Tests</name>
        <position>3</position>
    </quickFilter>
    

    XML Schema

    Source: xsd0.xsd

    <xs:element name="quickFilter" type="restQuickFilter"/><xs:element name="quickFilter" type="restQuickFilter"/>

available response representations:

  • 200 - application/json [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <quickFilter>
        <id>100623</id>
        <name>Integration Tests</name>
        <position>3</position>
        <hasRules>false</hasRules>
    </quickFilter>
    

    Returned when quick filter was updated successfully. Response will contain Quick Filter definition with data after update.

  • 400 - application/json [expand]

    When any validation errors occur or no quick filter was found with given ID. Response will contain all error messages.

DELETE

Delete a quick filter.

available response representations:

  • 400 - application/json [expand]

    Sent when quick filter was not found with the given ID.

  • 204 - application/json [expand]

    Returned when quick filter was deleted successfully.

/quickFilter/active

Methods

GET

Return active quick filters for currently logged in user.

available response representations:

  • 200 - application/json [expand]

    List of active quick filters for logged in user. Each entity will contain only basic configuration, excluding e.g. quick filter's rules.

/quickFilter/{id}/activate

resource-wide template parameters
parameter value description

id

long

Methods

PUT

Activates a quick filter for currently logged in user.

available response representations:

  • 200 - application/json [expand]

    Returned without any content when filter with given ID was successfully activated for current user.

  • 400 - application/json [expand]

    Sent when quick filter was not found with the given ID.

/quickFilter/{id}/deactivate

resource-wide template parameters
parameter value description

id

long

Methods

PUT

Deactivates a quick filter for currently logged in user.

available response representations:

  • 200 - application/json [expand]

    Returned without any content when filter with given ID was successfully deactivated for current user.

  • 400 - application/json [expand]

    Sent when quick filter was not found with the given ID.

/quickFilter/deactivate

Methods

PUT

Deactivates all quick filter for currently logged in user.

available response representations:

  • 200 - application/json [expand]

    Returned without any content when all filters were successfully deactivated for current user.

/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]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="deploymentResult" type="restDeploymentResult"/><xs:element name="deploymentResult" type="restDeploymentResult"/>

/server

Methods

GET

available response representations:

  • application/xml (restServerStatusInfo) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="restServerStatusInfo" type="restServerStatusInfo"/><xs:element name="restServerStatusInfo" type="restServerStatusInfo"/>
  • application/json (restServerStatusInfo) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="restServerStatusInfo" type="restServerStatusInfo"/><xs:element name="restServerStatusInfo" type="restServerStatusInfo"/>

/server/pause

Methods

POST

Pauses the server

available response representations:

  • application/xml (restServerStatusInfo) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="restServerStatusInfo" type="restServerStatusInfo"/><xs:element name="restServerStatusInfo" type="restServerStatusInfo"/>
  • application/json (restServerStatusInfo) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="restServerStatusInfo" type="restServerStatusInfo"/><xs:element name="restServerStatusInfo" type="restServerStatusInfo"/>

/server/prepareForRestart

Methods

PUT

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

available response representations:

  • application/xml (restServerStatusInfo) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="restServerStatusInfo" type="restServerStatusInfo"/><xs:element name="restServerStatusInfo" type="restServerStatusInfo"/>
  • application/json (restServerStatusInfo) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="restServerStatusInfo" type="restServerStatusInfo"/><xs:element name="restServerStatusInfo" type="restServerStatusInfo"/>

/server/resume

Methods

POST

Resumes the server

available response representations:

  • application/xml (restServerStatusInfo) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="restServerStatusInfo" type="restServerStatusInfo"/><xs:element name="restServerStatusInfo" type="restServerStatusInfo"/>
  • application/json (restServerStatusInfo) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="restServerStatusInfo" type="restServerStatusInfo"/><xs:element name="restServerStatusInfo" type="restServerStatusInfo"/>

/repository

Methods

/repository/{repositoryId}/rssrepository/search?searchTerm

resource-wide template parameters
parameter value description

repositoryId

long

Methods

GET

Search for existing linked repositories which can be granted to use given repository by RSS.

request query parameters
parameter value description

searchTerm

string

available response representations:

  • 200 [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restRepositoryList start-index="0" max-result="1" size="2">
        <searchResults>
            <id>123</id>
            <name>linked repository 1</name>
            <url>http://localhost:8085/admin/configureLinkedRepositories.action?repositoryId=123</url>
            <rssEnabled>true</rssEnabled>
        </searchResults>
        <searchResults>
            <id>321</id>
            <name>linked repository 2</name>
            <url>http://localhost:8085/admin/configureLinkedRepositories.action?repositoryId=321</url>
            <rssEnabled>true</rssEnabled>
        </searchResults>
    </restRepositoryList>
    

    The page object with repositories.

  • 403 [expand]

    Returned when user has insufficient permissions to target repository

  • 404 [expand]

    Returned when specified repository not found or repository stored Bamboo specs feature is disabled

/repository/testConnection

Methods

PUT

Tests connection to a repository if the repository type supports connection testing. Request payload should contain repository configuration.

acceptable request representations:

available response representations:

  • 200 - application/json [expand]

    Successful call (without validation errors) will result in HTTP 200. The response will contain potential connection errors. If the connection to repository was successful, the error list will be empty.

  • 400 - application/json [expand]

    A response with code HTTP 400 indicates that there were validation errors before attempting to connect to repository. The response will contain error messages and field errors. This response will also be sent if the repository type doesn't support connection testing.

  • 401 - application/json [expand]

    A response with code HTTP 401 indicates that the calling user had insufficient permissions, e.g. for a plan or a repository

/repository/{repositoryId}/enableCi

resource-wide template parameters
parameter value description

repositoryId

long

id of the repository

Methods

PUT

Enables or disables detection of Bamboo Specs stored in the repository. If enabled, code changes detected in Bamboo Specs in new commits will trigger execution of Bamboo Specs and thus an update of corresponding entities (such as build plans, deployments or permissions). <p> Request body is JSON with one attribute : <pre> { enable: true/false } </pre>

acceptable request representations:

available response representations:

  • 200 - application/json [expand]

    Successful call will result in HTTP 200.

  • 400 - application/json [expand]

    This repository does not handle 'enableCi' feature or input data is incorrect.

  • 401 - application/json [expand]

    The calling user has insufficient permissions to change this setting.

  • 500 - application/json [expand]

    Internal server error

/repository/{repositoryId}/enableAllProjectsAccess

resource-wide template parameters
parameter value description

repositoryId

long

id of the repository

Methods

PUT

Enables access (i.e. allowing modifications) for all Bamboo projects by the Bamboo Specs code stored in this repository. Changes in Bamboo Specs detected will trigger execution of Specs and thus an update of corresponding entities (such as build plans or deployments). <p> <p/> Request body is JSON with one attribute : <pre> { enable: true/false } </pre>

acceptable request representations:

available response representations:

  • 200 - application/json [expand]

    Successful call will result in HTTP 200.

  • 400 - application/json [expand]

    This repository does not handle 'enableAllProjectsAccess' feature or input data is incorrect.

  • 401 - application/json [expand]

    The calling user has insufficient permissions to change this setting.

  • 500 - application/json [expand]

    Internal server error

/repository/{repositoryId}/enableAllRepositoriesAccess

resource-wide template parameters
parameter value description

repositoryId

long

id of the repository

Methods

PUT

Enables access (i.e. allowing modifications) for all Bamboo linked repositories by the Bamboo Specs code stored in this repository. <p> <p/> Request body is JSON with one attribute : <pre> { enable: true/false } </pre>

acceptable request representations:

available response representations:

  • 200 - application/json [expand]

    Successful call will result in HTTP 200.

  • 400 - application/json [expand]

    This repository does not handle 'enableAllRepositoriesAccess' feature or input data is incorrect.

  • 401 - application/json [expand]

    The calling user has insufficient permissions to change this setting.

  • 500 - application/json [expand]

    Internal server error

/repository/{repositoryId}/rssrepository

resource-wide template parameters
parameter value description

repositoryId

long

target repository id

Methods

POST

Grant repository with RSS code to use target repository in build plans and deployments. If permission is not granted RSS import will fail when code tries to use target repository.

acceptable request representations:

  • application/json (restIdContainer) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="restIdContainer" type="restIdContainer"/><xs:element name="restIdContainer" type="restIdContainer"/>

available response representations:

  • 201 [expand]

    Example
    {"id":"123", "name":"repo1", "url":"http://localhost:8085/admin/configureLinkedRepositories.action?repositoryId=123"}

    permission granted.

  • 400 [expand]

    Returned when repository id is empty or null

  • 403 [expand]

    Returned when user has insufficient permissions to target repository

  • 404 [expand]

    Returned when specified repository not found by id or repository stored Bamboo specs feature is disabled

GET

Fetch list of RSS repositories which can use given repository by RSS code.

available response representations:

  • 200 [expand]

    Example
    [{"id":"123", "name":"repo1", "url":"http://localhost:8085/admin/configureLinkedRepositories.action?repositoryId=123"}]

    The page object with list of repositories.

  • 403 [expand]

    Returned when user has insufficient permissions to target repository

  • 404 [expand]

    Returned when specified repository not found or repository stored Bamboo specs feature is disabled

/repository/{targetRepositoryId}/rssrepository/{repositoryId}

resource-wide template parameters
parameter value description

repositoryId

long

linked repository root id

targetRepositoryId

long

target repository id

Methods

DELETE

Revoke access of RSS code stored in repository defined by repositoryId from repository defined by targetRepositoryId. Use this method when need to prevent usage of target repository by RSS code stored in repository referenced by repositoryId.

available response representations:

  • 204 [expand]

    When successfully removed link between target repository and repository.

  • 403 [expand]

    Returned when user has insufficient permissions to repository

  • 404 [expand]

    Returned when specified repository does not exist or repository stored Bamboo specs feature is disabled

/repository/{repositoryId}/scan/status?max-result

resource-wide template parameters
parameter value description

repositoryId

long

ID of the linked repository which stores Bamboo Specs

Methods

GET

Resource providing status of RSS processing for a given repository.

request query parameters
parameter value description

max-result

int

maximum number of spec status entries returned in the response

available response representations:

  • 200 - application/json [expand]

    The object representing RSS status

  • 404 [expand]

    Returned when Bamboo Specs feature is disabled in Bamboo, or when a repository with given ID could not be found

/repository/scan?id&repositoryId&name&repositoryName

Methods

POST

Webhook resource for triggering Repository-stored Bamboo Specs. Either repository ID or name must be provided via query parameters to identify the linked repository in which Bamboo Specs are defined. <p> Ambiguous requests, which reference more than one repository via the query params, will result in one parameter taking precedence over the others. There's no guarantee which one. <p> This resource does not require authorisation. It will always return HTTP 204 response on every valid request, even if the targeted repository doesn't exist or does not contain Bamboo Specs.

request query parameters
parameter value description

id

long

ID of the linked repository which stores Bamboo Specs

repositoryId

long

alternative name of the query parameter to provide repository ID

name

string

unique name of the linked repository which stores Bamboo Specs

repositoryName

string

alternative name of the query parameter to provide repository name

available response representations:

  • 400 [expand]

    Returned when neither repository ID nor repository name were provided.

  • 204 [expand]

    Returned on any valid request.

  • 404 [expand]

    Returned when Bamboo Specs feature is disabled in Bamboo

/repository/{repositoryId}/scanNow

resource-wide template parameters
parameter value description

repositoryId

long

alternative name of the query parameter to provide repository ID

Methods

POST

Webhook resource for triggering Repository-stored Bamboo Specs. Either repository ID or name must be provided via query parameters to identify the linked repository in which Bamboo Specs are defined. <p> Ambiguous requests, which reference more than one repository via the query params, will result in one parameter taking precedence over the others. There's no guarantee which one. <p> This resource does not require authorisation. It will always return HTTP 204 response on every valid request, even if the targeted repository doesn't exist or does not contain Bamboo Specs.

available response representations:

  • 400 [expand]

    Returned when neither repository ID nor repository name were provided.

  • 204 [expand]

    Returned on any valid request.

  • 404 [expand]

    Returned when Bamboo Specs feature is disabled in Bamboo

/deploy/dashboard

Methods

GET

available response representations:

  • application/json (dashboardProjectWithEnvironmentStatus) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="dashboardProjectWithEnvironmentStatus" type="dashboardProjectWithEnvironmentStatus"/><xs:element name="dashboardProjectWithEnvironmentStatus" type="dashboardProjectWithEnvironmentStatus"/>

/deploy/dashboard/{projectId}

resource-wide template parameters
parameter value description

projectId

long

Methods

GET

available response representations:

  • application/json (dashboardProjectWithEnvironmentStatus) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="dashboardProjectWithEnvironmentStatus" type="dashboardProjectWithEnvironmentStatus"/><xs:element name="dashboardProjectWithEnvironmentStatus" type="dashboardProjectWithEnvironmentStatus"/>

/

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]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <resources>
        <resources start-index="0" max-result="0" size="0">
            <resource name="info">
                <link href="http://localhost:8085/bamboo/rest/api/latest/info" rel="self"/>
            </resource>
            <resource name="project">
                <link href="http://localhost:8085/bamboo/rest/api/latest/project" rel="self"/>
            </resource>
            <resource name="plan">
                <link href="http://localhost:8085/bamboo/rest/api/latest/plan" rel="self"/>
            </resource>
            <resource name="result">
                <link href="http://localhost:8085/bamboo/rest/api/latest/result" rel="self"/>
            </resource>
            <resource name="chart">
                <link href="http://localhost:8085/bamboo/rest/api/latest/chart" rel="self"/>
            </resource>
            <resource name="queue">
                <link href="http://localhost:8085/bamboo/rest/api/latest/queue" rel="self"/>
            </resource>
            <resource name="export">
                <link href="http://localhost:8085/bamboo/rest/api/latest/export" rel="self"/>
            </resource>
            <resource name="clone">
                <link href="http://localhost:8085/bamboo/rest/api/latest/clone" rel="self"/>
            </resource>
            <resource name="currentUser">
                <link href="http://localhost:8085/bamboo/rest/api/latest/currentUser" rel="self"/>
            </resource>
        </resources>
    </resources>
    

    List of available REST resources

    XML Schema

    Source:

/plan/favicon

Methods

/plan/favicon/{planKey}

resource-wide template parameters
parameter value description

planKey

string

Methods

GET

available response representations:

  • application/json (favicon) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="favicon" type="restFavicon"/><xs:element name="favicon" type="restFavicon"/>

/agent?online

Methods

GET

Provides a list of all agents. Use query parameter "online = true/false" to filter only online agents.

request query parameters
parameter value description

online

boolean

available response representations:

  • 200 - application/json [expand]

    A successful call will return a complete (non-paginated) list of agents

  • 401 - application/json [expand]

    A response with code HTTP 401 indicates that the calling user had insufficient permissions for the request.

/agent/remote?online

Methods

GET

Provides a list of all agent authentication statuses. Use query parameter "online = true/false" to filter only remote or only approved agents.

request query parameters
parameter value description

online

boolean

available response representations:

  • 200 - application/json [expand]

    A successful call will return a complete (non-paginated) list of remote agents

  • 401 - application/json [expand]

    A response with code HTTP 401 indicates that the calling user had insufficient permissions for the request.

/permissions/global

REST endpoint to manage user/group global permissions in Bamboo.

Methods

/permissions/global/users?ignore&name

Methods

GET

Retrieve a list of users with their global permissions. The list can be filtered by some attributes. This resource is paged and returns a single page of results.

request query parameters
parameter value description

ignore

string

parameter not used, can be ignored

name

string

user filter, filter is case insensitive matches: username, user's full name, user's email

available response representations:

  • 200 [expand]

    Return single page of users with their permissions

  • 401 [expand]

    If the user lacks global admin or restricted admin permission.

/permissions/global/users/{name : (.+)?}?ignore

resource-wide template parameters
parameter value description

name

string

username of the affected user

Methods

PUT

Grants global permissions to a given user.

request query parameters
parameter value description

ignore

string

parameter not used, can be ignored

available response representations:

  • 400 [expand]

    If 'username' user doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks global admin or restricted admin permission.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If user already had requested permissions and permission state hasn't been changed.

DELETE

Revokes global permissions from a given user.

request query parameters
parameter value description

ignore

string

parameter not used, can be ignored

available response representations:

  • 400 [expand]

    If the 'username' user doesn't exist.

  • 401 [expand]

    If the user lacks global admin or restricted admin permission.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If user already lacked requested permissions and permission state hasn't been changed.

/permissions/global/available-users?ignore&name

Methods

GET

Returns list of users which weren't granted explicitly any permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

ignore

string

user filter, filter is case insensitive matches: username, user's full name, user's email

name

string

represents the params that define which page the request is after

available response representations:

  • 200 [expand]

    Return single page of users which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks global admin or restricted admin permission.

/permissions/global/groups?ignore&name

Methods

GET

Retrieve a list of groups with their global permissions. The list can be filtered by some attributes. This resource is paged returns a single page of results.

request query parameters
parameter value description

ignore

string

parameter not used, can be ignored

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups with their permissions

  • 401 [expand]

    If the user lacks global admin or restricted admin permission.

/permissions/global/groups/{name : (.+)?}?ignore

resource-wide template parameters
parameter value description

name

string

affected group

Methods

PUT

Grants global permissions to a given group.

request query parameters
parameter value description

ignore

string

parameter not used, can be ignored

available response representations:

  • 400 [expand]

    If group doesn't exist or one of the requested permission isn't supported for given endpoint.

  • 401 [expand]

    If the user lacks global admin or restricted admin permission.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If group already had requested permissions and permission state hasn't been changed.

DELETE

Revokes global permissions from a given group.

request query parameters
parameter value description

ignore

string

parameter not used, can be ignored

available response representations:

  • 400 [expand]

    If group doesn't exist.

  • 401 [expand]

    If the user lacks global admin or restricted admin permission.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If group already lacked requested permissions and permission state hasn't been changed.

/permissions/global/available-groups?ignore&name

Methods

GET

Returns list of groups which weren't granted explicitly any permissions. Resource is paged, returns single page of resources.

request query parameters
parameter value description

ignore

string

parameter not used, can be ignored

name

string

group name filter, filter is case insensitive matches group name

available response representations:

  • 200 [expand]

    Return single page of groups which don't have any explicit permissions granted

  • 401 [expand]

    If the user lacks global admin or restricted admin permission.

/permissions/global/roles?ignore

Methods

GET

Retrieve a list of roles with their global permissions. This resource is paged returns a single page of results, although only 2 roles are supported: LOGGED IN users, ANONYMOUS users

request query parameters
parameter value description

ignore

string

parameter not used, can be ignored

available response representations:

  • 200 [expand]

    Return single page of roles with their permissions

  • 401 [expand]

    If the user lacks global admin or restricted admin permission.

/permissions/global/roles/{name : (.+)?}?ignore

resource-wide template parameters
parameter value description

name

string

affected role

Methods

PUT

Grants global permissions to a given role.

request query parameters
parameter value description

ignore

string

parameter not used, can be ignored

available response representations:

  • 400 [expand]

    If role doesn't exist or one of the requested permission isn't supported for given role. Anonymous role supports only VIEW permission.

  • 401 [expand]

    If the user lacks global admin or restricted admin permission.

  • 204 [expand]

    If permissions were granted.

  • 304 [expand]

    If role already had requested permissions and permission state hasn't been changed.

DELETE

Revokes global permissions from a given role.

request query parameters
parameter value description

ignore

string

parameter not used, can be ignored

available response representations:

  • 400 [expand]

    If role doesn't exist.

  • 401 [expand]

    If the user lacks global admin or restricted admin permission.

  • 204 [expand]

    If permissions were revoked.

  • 304 [expand]

    If role already lacked requested permissions and permission state hasn't been changed.

/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]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <queue expand="queuedBuilds">
        <queuedBuilds start-index="0" max-result="1" size="0">
            <queuedBuild expand="queuedBuild" planKey="PROJECTKEY-PLANKEY" buildNumber="10" buildResultKey="PROJECTKEY-PLANKEY-10">
                <triggerReason>Manual build</triggerReason>
                <changes expand="changes" start-index="0" max-result="2" size="0">
                    <change expand="change" author="Author" changesetId="10">
                        <comment>Sample comment</comment>
                        <date>2018-09-25T13:29:33.959Z</date>
                        <files start-index="0" max-result="3" size="0">
                            <file>
                                <name>some/example/path/to/File.java</name>
                                <revision>10</revision>
                            </file>
                            <file>
                                <name>some/example/path/to/File.java</name>
                                <revision>10</revision>
                            </file>
                            <file>
                                <name>some/example/path/to/File.java</name>
                                <revision>10</revision>
                            </file>
                        </files>
                    </change>
                    <change expand="change" author="Author" changesetId="10">
                        <comment>Sample comment</comment>
                        <date>2018-09-25T13:29:33.959Z</date>
                        <files start-index="0" max-result="3" size="0">
                            <file>
                                <name>some/example/path/to/File.java</name>
                                <revision>10</revision>
                            </file>
                            <file>
                                <name>some/example/path/to/File.java</name>
                                <revision>10</revision>
                            </file>
                            <file>
                                <name>some/example/path/to/File.java</name>
                                <revision>10</revision>
                            </file>
                        </files>
                    </change>
                </changes>
            </queuedBuild>
        </queuedBuilds>
    </queue>
    

    List of queued builds waiting in the build queue

    XML Schema

    Source:

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

resource-wide template parameters
parameter value description

projectKey

string

buildKey

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:

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

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restQueuedBuild expand="queuedBuild" planKey="PROJECTKEY-PLANKEY" buildNumber="10" buildResultKey="PROJECTKEY-PLANKEY-10">
        <triggerReason>Manual build</triggerReason>
        <changes expand="changes" start-index="0" max-result="2" size="0">
            <change expand="change" author="Author" changesetId="10">
                <comment>Sample comment</comment>
                <date>2018-09-25T13:29:33.959Z</date>
                <files start-index="0" max-result="3" size="0">
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                </files>
            </change>
            <change expand="change" author="Author" changesetId="10">
                <comment>Sample comment</comment>
                <date>2018-09-25T13:29:33.959Z</date>
                <files start-index="0" max-result="3" size="0">
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                </files>
            </change>
        </changes>
    </restQueuedBuild>
    

    Information for queued build, including build number, changes and reason of build

    XML Schema

    Source:

  • 400 [expand]

    Returned when build was not added to the queue because of Bamboo limitation - for example too many concurrent builds running for requested plan already

  • 401 [expand]

    Returned when user does not have sufficient rights to view or execute build for specified plan

  • 404 [expand]

    Returned when specified plan does not exist or plan is not a top level plan

  • 415 [expand]

    Returned when POST method payload is not form encoded

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

resource-wide template parameters
parameter value description

projectKey

string

project key

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.

buildNumber

int

build number

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:

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

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <restQueuedBuild expand="queuedBuild" planKey="PROJECTKEY-PLANKEY" buildNumber="10" buildResultKey="PROJECTKEY-PLANKEY-10">
        <triggerReason>Manual build</triggerReason>
        <changes expand="changes" start-index="0" max-result="2" size="0">
            <change expand="change" author="Author" changesetId="10">
                <comment>Sample comment</comment>
                <date>2018-09-25T13:29:33.959Z</date>
                <files start-index="0" max-result="3" size="0">
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                </files>
            </change>
            <change expand="change" author="Author" changesetId="10">
                <comment>Sample comment</comment>
                <date>2018-09-25T13:29:33.959Z</date>
                <files start-index="0" max-result="3" size="0">
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                </files>
            </change>
        </changes>
    </restQueuedBuild>
    

    Information for queued build, including build number, changes and reason of build

    XML Schema

    Source:

  • 400 [expand]

    Returned when build is currently executing or is in state not allowing execution

  • 401 [expand]

    Returned when user does not have sufficient rights to view or execute build for specified plan

  • 404 [expand]

    Returned when specified plan does not exist, result for provided build number does not exist or is not top level plan result

DELETE

Stop build execution.

available response representations:

  • 401 [expand]

    Returned when user does not have sufficient rights to view or execute build for specified plan

  • 204 [expand]

    On success (success is also when build was already completed - so nothing to stop)

  • 404 [expand]

    Returned when specified job does not exist

/chart

Methods

GET

available response representations:

  • application/xml (chart) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="chart" type="restChart"/><xs:element name="chart" type="restChart"/>
  • application/json (chart) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="chart" type="restChart"/><xs:element name="chart" type="restChart"/>

/chart/reports

Methods

GET

available response representations:

  • application/xml (reports) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="reports" type="restReports"/><xs:element name="reports" type="restReports"/>
  • application/json (reports) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="reports" type="restReports"/><xs:element name="reports" type="restReports"/>

/chart/planSummary

Methods

GET

available response representations:

  • application/xml (chart) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="chart" type="restChart"/><xs:element name="chart" type="restChart"/>
  • application/json (chart) [expand]
    XML Schema

    Source: xsd0.xsd

    <xs:element name="chart" type="restChart"/><xs:element name="chart" type="restChart"/>

/agent/authentication?pending

Methods

GET

Provides a list of all agent authentication statuses. Use query parameter "pending = true/false" to filter only pending or only approved agents.

request query parameters
parameter value description

pending

boolean

available response representations:

  • 200 - application/json [expand]

    A successful call will return a complete (non-paginated) list of agent authentication statuses.

  • 401 - application/json [expand]

    A response with code HTTP 401 indicates that the calling user had insufficient permissions for the request.

/agent/authentication/{agentUuid}

resource-wide template parameters
parameter value description

agentUuid

string

Methods

PUT

Authenticates a pending agent with the given UUID. If the agent has already been authenticated, the call will not change it's state.

available response representations:

  • 400 - application/json [expand]

    A response with code HTTP 400 indicates that there were errors during request execution - for example data validation errors occurred (the provided UUID was invalid, no agent with the given UUID was found etc.).

  • 401 - application/json [expand]

    A response with code HTTP 401 indicates that the calling user had insufficient permissions for the request.

  • 204 [expand]

    No content response is sent after successful authentication of an agent.

/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]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <results>
        <results start-index="0" max-result="2" size="0">
            <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" key="PPROJECTKEY-PLANKEY-2" state="SUCCESS" lifeCycleState="Finished" number="2" id="10000" continuable="false" onceOff="false" restartable="false">
                <planName>PLAN_NAME</planName>
                <projectName>PROJECT_NAME</projectName>
                <buildStartedTime>2018-09-25T13:29:33.952Z</buildStartedTime>
                <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
                <buildCompletedTime>2018-09-25T13:29:33.952Z</buildCompletedTime>
                <buildCompletedDate>2018-09-25T13:29:33.952Z</buildCompletedDate>
                <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
                <buildDurationInSeconds>1</buildDurationInSeconds>
                <buildDuration>1000</buildDuration>
                <buildDurationDescription>1 second</buildDurationDescription>
                <buildRelativeTime>1 hour ago</buildRelativeTime>
                <queueStartedTime>2018-09-25T13:29:33.953Z</queueStartedTime>
                <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
                <restartCount>0</restartCount>
                <artifacts start-index="0" max-result="1" size="0">
                    <artifact>
                        <name>cargo log</name>
                        <link href="http://localhost:8085/bamboo/browse/PROJECTKEY-PLANKEY-2/artifact/shared/cargo-log.log" rel="self"/>
                        <producerJobKey>PROJECTKEY-PLANKEY-2</producerJobKey>
                        <shared>true</shared>
                        <size>1024</size>
                        <prettySizeDescription>1 kilobyte</prettySizeDescription>
                    </artifact>
                </artifacts>
                <comments start-index="0" max-result="2" size="0">
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                </comments>
                <labels start-index="0" max-result="2" size="0">
                    <label name="someLabel"/>
                    <label name="someLabel"/>
                </labels>
                <jiraIssues start-index="0" max-result="2" size="0">
                    <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
                    </issue>
                    <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
                    </issue>
                </jiraIssues>
            </result>
            <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" state="SUCCESS" lifeCycleState="Finished" number="2" id="10000" continuable="false" onceOff="false" restartable="false">
                <planName>ANOTHER_PLAN_NAME</planName>
                <projectName>ANOTHER_PROJECT_NAME</projectName>
                <buildStartedTime>2018-09-25T13:29:33.964Z</buildStartedTime>
                <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
                <buildCompletedTime>2018-09-25T13:29:33.964Z</buildCompletedTime>
                <buildCompletedDate>2018-09-25T13:29:33.964Z</buildCompletedDate>
                <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
                <buildDurationInSeconds>1</buildDurationInSeconds>
                <buildDuration>1000</buildDuration>
                <buildDurationDescription>1 second</buildDurationDescription>
                <buildRelativeTime>1 hour ago</buildRelativeTime>
                <queueStartedTime>2018-09-25T13:29:33.965Z</queueStartedTime>
                <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
                <restartCount>0</restartCount>
                <comments start-index="0" max-result="2" size="0">
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                </comments>
                <labels start-index="0" max-result="2" size="0">
                    <label name="someLabel"/>
                    <label name="someLabel"/>
                </labels>
                <jiraIssues start-index="0" max-result="2" size="0">
                    <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
                    </issue>
                    <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
                    </issue>
                </jiraIssues>
            </result>
        </results>
    </results>
    

    Latest build results for all plans

    XML Schema

    Source:

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

resource-wide template parameters
parameter value description

projectKey

string

project key

buildKey

string

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

buildNumber

string

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

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:

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

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" key="PPROJECTKEY-PLANKEY-2" state="SUCCESS" lifeCycleState="Finished" number="2" id="10000" continuable="false" onceOff="false" restartable="false">
        <planName>PLAN_NAME</planName>
        <projectName>PROJECT_NAME</projectName>
        <buildStartedTime>2018-09-25T13:29:33.952Z</buildStartedTime>
        <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
        <buildCompletedTime>2018-09-25T13:29:33.952Z</buildCompletedTime>
        <buildCompletedDate>2018-09-25T13:29:33.952Z</buildCompletedDate>
        <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
        <buildDurationInSeconds>1</buildDurationInSeconds>
        <buildDuration>1000</buildDuration>
        <buildDurationDescription>1 second</buildDurationDescription>
        <buildRelativeTime>1 hour ago</buildRelativeTime>
        <queueStartedTime>2018-09-25T13:29:33.953Z</queueStartedTime>
        <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
        <restartCount>0</restartCount>
        <artifacts start-index="0" max-result="1" size="0">
            <artifact>
                <name>cargo log</name>
                <link href="http://localhost:8085/bamboo/browse/PROJECTKEY-PLANKEY-2/artifact/shared/cargo-log.log" rel="self"/>
                <producerJobKey>PROJECTKEY-PLANKEY-2</producerJobKey>
                <shared>true</shared>
                <size>1024</size>
                <prettySizeDescription>1 kilobyte</prettySizeDescription>
            </artifact>
        </artifacts>
        <comments start-index="0" max-result="2" size="0">
            <comment author="bambooUser">
                <content>Sample comment for build</content>
                <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
            </comment>
            <comment author="bambooUser">
                <content>Sample comment for build</content>
                <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
            </comment>
        </comments>
        <labels start-index="0" max-result="2" size="0">
            <label name="someLabel"/>
            <label name="someLabel"/>
        </labels>
        <jiraIssues start-index="0" max-result="2" size="0">
            <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
            </issue>
            <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
            </issue>
        </jiraIssues>
        <changes expand="changes" start-index="0" max-result="2" size="0">
            <change expand="change" author="Author" changesetId="10">
                <comment>Sample comment</comment>
                <date>2018-09-25T13:29:33.959Z</date>
                <files start-index="0" max-result="3" size="0">
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                </files>
            </change>
            <change expand="change" author="Author" changesetId="10">
                <comment>Sample comment</comment>
                <date>2018-09-25T13:29:33.959Z</date>
                <files start-index="0" max-result="3" size="0">
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                </files>
            </change>
        </changes>
        <metadata start-index="0" max-result="1" size="0">
            <item key="ManualBuildTriggerReason.userName" value="admin"/>
        </metadata>
    </result>
    

    Result of single build. Presented content contain information for finished build. If build is in progress, contains additional runtime information. Top level plan contains additionally progress information, job progress information, current log entries and hasExecutableAgent boolean flag.

    XML Schema

    Source:

  • 401 [expand]

    Returned when user has no permission to view specified plan

  • 404 [expand]

    Returned when specified project or plan does not exists

/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]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <results>
        <results start-index="0" max-result="2" size="0">
            <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" key="ANOTHERPPROJECTKEY-ANOTHERPLANKEY-2" state="SUCCESS" lifeCycleState="Finished" number="1" id="10000" continuable="false" onceOff="false" restartable="false">
                <planName>PLAN_NAME</planName>
                <projectName>PROJECT_NAME</projectName>
                <buildStartedTime>2018-09-25T13:29:33.964Z</buildStartedTime>
                <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
                <buildCompletedTime>2018-09-25T13:29:33.964Z</buildCompletedTime>
                <buildCompletedDate>2018-09-25T13:29:33.964Z</buildCompletedDate>
                <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
                <buildDurationInSeconds>1</buildDurationInSeconds>
                <buildDuration>1000</buildDuration>
                <buildDurationDescription>1 second</buildDurationDescription>
                <buildRelativeTime>1 hour ago</buildRelativeTime>
                <queueStartedTime>2018-09-25T13:29:33.964Z</queueStartedTime>
                <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
                <restartCount>0</restartCount>
                <comments start-index="0" max-result="2" size="0">
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                </comments>
                <labels start-index="0" max-result="2" size="0">
                    <label name="someLabel"/>
                    <label name="someLabel"/>
                </labels>
                <jiraIssues start-index="0" max-result="2" size="0">
                    <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
                    </issue>
                    <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
                    </issue>
                </jiraIssues>
            </result>
            <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" key="PPROJECTKEY-PLANKEY-2" state="SUCCESS" lifeCycleState="Finished" number="2" id="10000" continuable="false" onceOff="false" restartable="false">
                <planName>PLAN_NAME</planName>
                <projectName>PROJECT_NAME</projectName>
                <buildStartedTime>2018-09-25T13:29:33.952Z</buildStartedTime>
                <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
                <buildCompletedTime>2018-09-25T13:29:33.952Z</buildCompletedTime>
                <buildCompletedDate>2018-09-25T13:29:33.952Z</buildCompletedDate>
                <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
                <buildDurationInSeconds>1</buildDurationInSeconds>
                <buildDuration>1000</buildDuration>
                <buildDurationDescription>1 second</buildDurationDescription>
                <buildRelativeTime>1 hour ago</buildRelativeTime>
                <queueStartedTime>2018-09-25T13:29:33.953Z</queueStartedTime>
                <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
                <restartCount>0</restartCount>
                <artifacts start-index="0" max-result="1" size="0">
                    <artifact>
                        <name>cargo log</name>
                        <link href="http://localhost:8085/bamboo/browse/PROJECTKEY-PLANKEY-2/artifact/shared/cargo-log.log" rel="self"/>
                        <producerJobKey>PROJECTKEY-PLANKEY-2</producerJobKey>
                        <shared>true</shared>
                        <size>1024</size>
                        <prettySizeDescription>1 kilobyte</prettySizeDescription>
                    </artifact>
                </artifacts>
                <comments start-index="0" max-result="2" size="0">
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                </comments>
                <labels start-index="0" max-result="2" size="0">
                    <label name="someLabel"/>
                    <label name="someLabel"/>
                </labels>
                <jiraIssues start-index="0" max-result="2" size="0">
                    <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
                    </issue>
                    <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
                    </issue>
                </jiraIssues>
            </result>
        </results>
    </results>
    

    Build results for specified changeset.

    XML Schema

    Source:

/result/byCheckoutChangeset/{csid}

resource-wide template parameters
parameter value description

csid

string

checkout 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 which have repositories checked out with this changeset.

available response representations:

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

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <results>
        <results start-index="0" max-result="2" size="0">
            <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" key="ANOTHERPPROJECTKEY-ANOTHERPLANKEY-2" state="SUCCESS" lifeCycleState="Finished" number="1" id="10000" continuable="false" onceOff="false" restartable="false">
                <planName>PLAN_NAME</planName>
                <projectName>PROJECT_NAME</projectName>
                <buildStartedTime>2018-09-25T13:29:33.964Z</buildStartedTime>
                <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
                <buildCompletedTime>2018-09-25T13:29:33.964Z</buildCompletedTime>
                <buildCompletedDate>2018-09-25T13:29:33.964Z</buildCompletedDate>
                <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
                <buildDurationInSeconds>1</buildDurationInSeconds>
                <buildDuration>1000</buildDuration>
                <buildDurationDescription>1 second</buildDurationDescription>
                <buildRelativeTime>1 hour ago</buildRelativeTime>
                <queueStartedTime>2018-09-25T13:29:33.964Z</queueStartedTime>
                <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
                <restartCount>0</restartCount>
                <comments start-index="0" max-result="2" size="0">
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                </comments>
                <labels start-index="0" max-result="2" size="0">
                    <label name="someLabel"/>
                    <label name="someLabel"/>
                </labels>
                <jiraIssues start-index="0" max-result="2" size="0">
                    <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
                    </issue>
                    <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
                    </issue>
                </jiraIssues>
            </result>
            <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" key="PPROJECTKEY-PLANKEY-2" state="SUCCESS" lifeCycleState="Finished" number="2" id="10000" continuable="false" onceOff="false" restartable="false">
                <planName>PLAN_NAME</planName>
                <projectName>PROJECT_NAME</projectName>
                <buildStartedTime>2018-09-25T13:29:33.952Z</buildStartedTime>
                <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
                <buildCompletedTime>2018-09-25T13:29:33.952Z</buildCompletedTime>
                <buildCompletedDate>2018-09-25T13:29:33.952Z</buildCompletedDate>
                <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
                <buildDurationInSeconds>1</buildDurationInSeconds>
                <buildDuration>1000</buildDuration>
                <buildDurationDescription>1 second</buildDurationDescription>
                <buildRelativeTime>1 hour ago</buildRelativeTime>
                <queueStartedTime>2018-09-25T13:29:33.953Z</queueStartedTime>
                <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
                <restartCount>0</restartCount>
                <artifacts start-index="0" max-result="1" size="0">
                    <artifact>
                        <name>cargo log</name>
                        <link href="http://localhost:8085/bamboo/browse/PROJECTKEY-PLANKEY-2/artifact/shared/cargo-log.log" rel="self"/>
                        <producerJobKey>PROJECTKEY-PLANKEY-2</producerJobKey>
                        <shared>true</shared>
                        <size>1024</size>
                        <prettySizeDescription>1 kilobyte</prettySizeDescription>
                    </artifact>
                </artifacts>
                <comments start-index="0" max-result="2" size="0">
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                </comments>
                <labels start-index="0" max-result="2" size="0">
                    <label name="someLabel"/>
                    <label name="someLabel"/>
                </labels>
                <jiraIssues start-index="0" max-result="2" size="0">
                    <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
                    </issue>
                    <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
                    </issue>
                </jiraIssues>
            </result>
        </results>
    </results>
    

    Build results for specified changeset.

    XML Schema

    Source:

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

resource-wide template parameters
parameter value description

projectKey

string

project key

buildKey

string

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

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:

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

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <results>
        <results start-index="0" max-result="2" size="0">
            <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" key="ANOTHERPPROJECTKEY-ANOTHERPLANKEY-2" state="SUCCESS" lifeCycleState="Finished" number="1" id="10000" continuable="false" onceOff="false" restartable="false">
                <planName>PLAN_NAME</planName>
                <projectName>PROJECT_NAME</projectName>
                <buildStartedTime>2018-09-25T13:29:33.964Z</buildStartedTime>
                <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
                <buildCompletedTime>2018-09-25T13:29:33.964Z</buildCompletedTime>
                <buildCompletedDate>2018-09-25T13:29:33.964Z</buildCompletedDate>
                <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
                <buildDurationInSeconds>1</buildDurationInSeconds>
                <buildDuration>1000</buildDuration>
                <buildDurationDescription>1 second</buildDurationDescription>
                <buildRelativeTime>1 hour ago</buildRelativeTime>
                <queueStartedTime>2018-09-25T13:29:33.964Z</queueStartedTime>
                <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
                <restartCount>0</restartCount>
                <comments start-index="0" max-result="2" size="0">
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                </comments>
                <labels start-index="0" max-result="2" size="0">
                    <label name="someLabel"/>
                    <label name="someLabel"/>
                </labels>
                <jiraIssues start-index="0" max-result="2" size="0">
                    <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
                    </issue>
                    <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
                    </issue>
                </jiraIssues>
            </result>
            <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" key="PPROJECTKEY-PLANKEY-2" state="SUCCESS" lifeCycleState="Finished" number="2" id="10000" continuable="false" onceOff="false" restartable="false">
                <planName>PLAN_NAME</planName>
                <projectName>PROJECT_NAME</projectName>
                <buildStartedTime>2018-09-25T13:29:33.952Z</buildStartedTime>
                <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
                <buildCompletedTime>2018-09-25T13:29:33.952Z</buildCompletedTime>
                <buildCompletedDate>2018-09-25T13:29:33.952Z</buildCompletedDate>
                <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
                <buildDurationInSeconds>1</buildDurationInSeconds>
                <buildDuration>1000</buildDuration>
                <buildDurationDescription>1 second</buildDurationDescription>
                <buildRelativeTime>1 hour ago</buildRelativeTime>
                <queueStartedTime>2018-09-25T13:29:33.953Z</queueStartedTime>
                <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
                <restartCount>0</restartCount>
                <artifacts start-index="0" max-result="1" size="0">
                    <artifact>
                        <name>cargo log</name>
                        <link href="http://localhost:8085/bamboo/browse/PROJECTKEY-PLANKEY-2/artifact/shared/cargo-log.log" rel="self"/>
                        <producerJobKey>PROJECTKEY-PLANKEY-2</producerJobKey>
                        <shared>true</shared>
                        <size>1024</size>
                        <prettySizeDescription>1 kilobyte</prettySizeDescription>
                    </artifact>
                </artifacts>
                <comments start-index="0" max-result="2" size="0">
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                </comments>
                <labels start-index="0" max-result="2" size="0">
                    <label name="someLabel"/>
                    <label name="someLabel"/>
                </labels>
                <jiraIssues start-index="0" max-result="2" size="0">
                    <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
                    </issue>
                    <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
                    </issue>
                </jiraIssues>
            </result>
        </results>
    </results>
    

    Latest build results for specified plan. Results are ordered from latest or oldest.

    XML Schema

    Source:

  • 401 [expand]

    Returned when user has no permission to view specified plan

  • 404 [expand]

    Returned when specified project or plan does not exists

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

resource-wide template parameters
parameter value description

projectKey

string

buildKey

string

branchName

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:

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

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <results>
        <results start-index="0" max-result="2" size="0">
            <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" key="ANOTHERPPROJECTKEY-ANOTHERPLANKEY-2" state="SUCCESS" lifeCycleState="Finished" number="1" id="10000" continuable="false" onceOff="false" restartable="false">
                <planName>PLAN_NAME</planName>
                <projectName>PROJECT_NAME</projectName>
                <buildStartedTime>2018-09-25T13:29:33.964Z</buildStartedTime>
                <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
                <buildCompletedTime>2018-09-25T13:29:33.964Z</buildCompletedTime>
                <buildCompletedDate>2018-09-25T13:29:33.964Z</buildCompletedDate>
                <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
                <buildDurationInSeconds>1</buildDurationInSeconds>
                <buildDuration>1000</buildDuration>
                <buildDurationDescription>1 second</buildDurationDescription>
                <buildRelativeTime>1 hour ago</buildRelativeTime>
                <queueStartedTime>2018-09-25T13:29:33.964Z</queueStartedTime>
                <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
                <restartCount>0</restartCount>
                <comments start-index="0" max-result="2" size="0">
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                </comments>
                <labels start-index="0" max-result="2" size="0">
                    <label name="someLabel"/>
                    <label name="someLabel"/>
                </labels>
                <jiraIssues start-index="0" max-result="2" size="0">
                    <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
                    </issue>
                    <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
                    </issue>
                </jiraIssues>
            </result>
            <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" key="PPROJECTKEY-PLANKEY-2" state="SUCCESS" lifeCycleState="Finished" number="2" id="10000" continuable="false" onceOff="false" restartable="false">
                <planName>PLAN_NAME</planName>
                <projectName>PROJECT_NAME</projectName>
                <buildStartedTime>2018-09-25T13:29:33.952Z</buildStartedTime>
                <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
                <buildCompletedTime>2018-09-25T13:29:33.952Z</buildCompletedTime>
                <buildCompletedDate>2018-09-25T13:29:33.952Z</buildCompletedDate>
                <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
                <buildDurationInSeconds>1</buildDurationInSeconds>
                <buildDuration>1000</buildDuration>
                <buildDurationDescription>1 second</buildDurationDescription>
                <buildRelativeTime>1 hour ago</buildRelativeTime>
                <queueStartedTime>2018-09-25T13:29:33.953Z</queueStartedTime>
                <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
                <restartCount>0</restartCount>
                <artifacts start-index="0" max-result="1" size="0">
                    <artifact>
                        <name>cargo log</name>
                        <link href="http://localhost:8085/bamboo/browse/PROJECTKEY-PLANKEY-2/artifact/shared/cargo-log.log" rel="self"/>
                        <producerJobKey>PROJECTKEY-PLANKEY-2</producerJobKey>
                        <shared>true</shared>
                        <size>1024</size>
                        <prettySizeDescription>1 kilobyte</prettySizeDescription>
                    </artifact>
                </artifacts>
                <comments start-index="0" max-result="2" size="0">
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                </comments>
                <labels start-index="0" max-result="2" size="0">
                    <label name="someLabel"/>
                    <label name="someLabel"/>
                </labels>
                <jiraIssues start-index="0" max-result="2" size="0">
                    <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
                    </issue>
                    <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
                    </issue>
                </jiraIssues>
            </result>
        </results>
    </results>
    

    Latest build results for specified plan. Results are ordered from latest or oldest.

    XML Schema

    Source:

  • 401 [expand]

    Returned when user has no permission to view specified plan

  • 404 [expand]

    Returned when specified project or plan does not exists

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

resource-wide template parameters
parameter value description

projectKey

string

project key

buildKey

string

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

buildNumber

string

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

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:

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

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" key="PPROJECTKEY-PLANKEY-2" state="SUCCESS" lifeCycleState="Finished" number="2" id="10000" continuable="false" onceOff="false" restartable="false">
        <planName>PLAN_NAME</planName>
        <projectName>PROJECT_NAME</projectName>
        <buildStartedTime>2018-09-25T13:29:33.952Z</buildStartedTime>
        <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
        <buildCompletedTime>2018-09-25T13:29:33.952Z</buildCompletedTime>
        <buildCompletedDate>2018-09-25T13:29:33.952Z</buildCompletedDate>
        <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
        <buildDurationInSeconds>1</buildDurationInSeconds>
        <buildDuration>1000</buildDuration>
        <buildDurationDescription>1 second</buildDurationDescription>
        <buildRelativeTime>1 hour ago</buildRelativeTime>
        <queueStartedTime>2018-09-25T13:29:33.953Z</queueStartedTime>
        <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
        <restartCount>0</restartCount>
        <artifacts start-index="0" max-result="1" size="0">
            <artifact>
                <name>cargo log</name>
                <link href="http://localhost:8085/bamboo/browse/PROJECTKEY-PLANKEY-2/artifact/shared/cargo-log.log" rel="self"/>
                <producerJobKey>PROJECTKEY-PLANKEY-2</producerJobKey>
                <shared>true</shared>
                <size>1024</size>
                <prettySizeDescription>1 kilobyte</prettySizeDescription>
            </artifact>
        </artifacts>
        <comments start-index="0" max-result="2" size="0">
            <comment author="bambooUser">
                <content>Sample comment for build</content>
                <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
            </comment>
            <comment author="bambooUser">
                <content>Sample comment for build</content>
                <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
            </comment>
        </comments>
        <labels start-index="0" max-result="2" size="0">
            <label name="someLabel"/>
            <label name="someLabel"/>
        </labels>
        <jiraIssues start-index="0" max-result="2" size="0">
            <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
            </issue>
            <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
            </issue>
        </jiraIssues>
        <changes expand="changes" start-index="0" max-result="2" size="0">
            <change expand="change" author="Author" changesetId="10">
                <comment>Sample comment</comment>
                <date>2018-09-25T13:29:33.959Z</date>
                <files start-index="0" max-result="3" size="0">
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                </files>
            </change>
            <change expand="change" author="Author" changesetId="10">
                <comment>Sample comment</comment>
                <date>2018-09-25T13:29:33.959Z</date>
                <files start-index="0" max-result="3" size="0">
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                    <file>
                        <name>some/example/path/to/File.java</name>
                        <revision>10</revision>
                    </file>
                </files>
            </change>
        </changes>
        <metadata start-index="0" max-result="1" size="0">
            <item key="ManualBuildTriggerReason.userName" value="admin"/>
        </metadata>
    </result>
    

    Result of single build. Presented content contain information for finished build. If build is in progress, contains additional runtime information. Top level plan contains additionally progress information, job progress information, current log entries and hasExecutableAgent boolean flag.

    XML Schema

    Source:

  • 401 [expand]

    Returned when user has no permission to view specified plan

  • 404 [expand]

    Returned when specified project or plan does not exists

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

resource-wide template parameters
parameter value description

projectKey

string

project key

buildKey

string

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

buildNumber

string

build number

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:

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

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <comments>
        <comments start-index="0" max-result="2" size="0">
            <comment author="bambooUser">
                <content>Sample comment for build</content>
                <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
            </comment>
            <comment author="bambooUser">
                <content>Sample comment for build</content>
                <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
            </comment>
        </comments>
    </comments>
    

    List of comments for build result

    XML Schema

    Source: xsd0.xsd

    <xs:element name="restCommentList" type="restCommentList"/><xs:element name="restCommentList" type="restCommentList"/>
  • 401 [expand]

    Returned when user has no permission to view specified plan

  • 404 [expand]

    Returned when specified project, plan or build result does not exists

POST

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

acceptable request representations:

  • application/xml (comment) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <comment>
        <content>new comment content</content>
    </comment>
    

    XML Schema

    Source: xsd0.xsd

    <xs:element name="comment" type="restComment"/><xs:element name="comment" type="restComment"/>
  • application/json (comment) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <comment>
        <content>new comment content</content>
    </comment>
    

    XML Schema

    Source: xsd0.xsd

    <xs:element name="comment" type="restComment"/><xs:element name="comment" type="restComment"/>

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

resource-wide template parameters
parameter value description

projectKey

string

project key

buildKey

string

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

buildNumber

string

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

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:

  • 200 (restBuildLabelList) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <labels>
        <labels start-index="0" max-result="2" size="0">
            <label name="someLabel"/>
            <label name="someLabel"/>
        </labels>
    </labels>
    

    List of comments for build result

    XML Schema

    Source: xsd0.xsd

    <xs:element name="restBuildLabelList" type="restBuildLabelList"/><xs:element name="restBuildLabelList" type="restBuildLabelList"/>
  • 401 [expand]

    Returned when user has no permission to view specified plan

  • 404 [expand]

    Returned when specified project, plan or build result does not exists

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]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <label name="someLabel"/>
    

    XML Schema

    Source: xsd0.xsd

    <xs:element name="label" type="restBuildLabel"/><xs:element name="label" type="restBuildLabel"/>
  • application/json (label) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <label name="someLabel"/>
    

    XML Schema

    Source: xsd0.xsd

    <xs:element name="label" type="restBuildLabel"/><xs:element name="label" type="restBuildLabel"/>

available response representations:

  • 401 [expand]

    Returned when user has no permission to view specified plan

  • 404 [expand]

    Returned when specified project, plan or build result does not exists

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

resource-wide template parameters
parameter value description

projectKey

string

buildKey

string

labelName

string

buildNumber

string

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.

available response representations:

  • 401 [expand]

    Returned when user has no permission to view specified plan

  • 404 [expand]

    Returned when specified project, plan, build result or label to remove does not exists

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

resource-wide template parameters
parameter value description

projectKey

string

project key

buildKey

string

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

buildNumber

string

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

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:

  • 200 (restResultStatus) [expand]

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <status expand="stages" key="PROJECTKEY-PLANKEY-100">
        <finished>false</finished>
        <prettyQueuedTime>2018-09-25T13:29:34</prettyQueuedTime>
        <progress>
            <isValid>true</isValid>
            <isUnderAverageTime>true</isUnderAverageTime>
            <percentageCompleted>0.4669655761516365</percentageCompleted>
            <percentageCompletedPretty>46%</percentageCompletedPretty>
            <prettyTimeRemaining>Approximately 2 minutes remaining</prettyTimeRemaining>
            <prettyTimeRemainingLong>Approximately 2 minutes remaining</prettyTimeRemainingLong>
            <averageBuildDuration>120000</averageBuildDuration>
            <prettyAverageBuildDuration>2 mins</prettyAverageBuildDuration>
            <buildTime>60000</buildTime>
            <prettyBuildTime>1 min</prettyBuildTime>
        </progress>
        <currentStage>first stage</currentStage>
        <stages expand="stage" start-index="0" max-result="1" size="0">
            <stage>
                <results expand="results" start-index="0" max-result="1" size="0">
                    <result expand="result" state="Unknown">
                        <progress>
                            <isValid>true</isValid>
                            <isUnderAverageTime>true</isUnderAverageTime>
                            <percentageCompleted>0.4669655761516365</percentageCompleted>
                            <percentageCompletedPretty>46%</percentageCompletedPretty>
                            <prettyTimeRemaining>Approximately 2 minutes remaining</prettyTimeRemaining>
                            <prettyTimeRemainingLong>Approximately 2 minutes remaining</prettyTimeRemainingLong>
                            <averageBuildDuration>120000</averageBuildDuration>
                            <prettyAverageBuildDuration>2 mins</prettyAverageBuildDuration>
                            <buildTime>60000</buildTime>
                            <prettyBuildTime>1 min</prettyBuildTime>
                        </progress>
                        <waiting>false</waiting>
                        <queued>false</queued>
                        <updatingSource>false</updatingSource>
                        <prettyVcsUpdateDuration>10 seconds</prettyVcsUpdateDuration>
                    </result>
                </results>
                <name>stageName</name>
                <description>stage description</description>
                <isBuilding>true</isBuilding>
                <isCompleted>false</isCompleted>
                <isSuccessful>false</isSuccessful>
                <index>0</index>
            </stage>
        </stages>
    </status>
    

    Currently executing build status

    XML Schema

    Source:

  • 401 [expand]

    Returned when user has no permission to view specified plan

  • 404 [expand]

    Returned when specified project, plan or build result does not exists. Also when build result is not currently executed ie. build has been completed already

/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:

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

    Example
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <results>
        <results start-index="0" max-result="1" size="0">
            <result expand="changes,metadata,artifacts,comments,labels,jiraIssues,stages" key="ANOTHERPPROJECTKEY-ANOTHERPLANKEY-2" state="SUCCESS" lifeCycleState="Finished" number="1" id="10000" continuable="false" onceOff="false" restartable="false">
                <planName>PLAN_NAME</planName>
                <projectName>PROJECT_NAME</projectName>
                <buildStartedTime>2018-09-25T13:29:33.964Z</buildStartedTime>
                <prettyBuildStartedTime>2018-09-25T13:29:33</prettyBuildStartedTime>
                <buildCompletedTime>2018-09-25T13:29:33.964Z</buildCompletedTime>
                <buildCompletedDate>2018-09-25T13:29:33.964Z</buildCompletedDate>
                <prettyBuildCompletedTime>2018-09-25T13:29:33</prettyBuildCompletedTime>
                <buildDurationInSeconds>1</buildDurationInSeconds>
                <buildDuration>1000</buildDuration>
                <buildDurationDescription>1 second</buildDurationDescription>
                <buildRelativeTime>1 hour ago</buildRelativeTime>
                <queueStartedTime>2018-09-25T13:29:33.964Z</queueStartedTime>
                <prettyQueueStartedTime>2018-09-25T13:29:33</prettyQueueStartedTime>
                <restartCount>0</restartCount>
                <comments start-index="0" max-result="2" size="0">
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                    <comment author="bambooUser">
                        <content>Sample comment for build</content>
                        <creationDate>2018-09-25T13:29:33.953Z</creationDate>
                        <modificationDate>2018-09-25T13:29:33.953Z</modificationDate>
                    </comment>
                </comments>
                <labels start-index="0" max-result="2" size="0">
                    <label name="someLabel"/>
                    <label name="someLabel"/>
                </labels>
                <jiraIssues start-index="0" max-result="2" size="0">
                    <issue key="BAM-9040" summary="Break out the Run options from the current menu" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9040" rel="self"/>
                    </issue>
                    <issue key="BAM-9137" summary="Task to allow users to tag and branch in SVN" iconUrl="https://jira.atlassian.com/images/icons/sales.gif" issueType="Story" status="Resolved">
                        <url href="https://jira.atlassian.com/browse/BAM-9137" rel="self"/>
                    </issue>
                </jiraIssues>
            </result>
        </results>
    </results>
    

    Latest build results for plans for specified project

    XML Schema

    Source:

  • 404 [expand]

    Returned when specified project does not exists or user does not have permission to see plans for specified project