The Bamboo REST API

We’re making changes to our server and Data Center products, including the end of sale for new server licenses on February 2, 2021 and the end of support for server on February 2, 2024. Learn what this means for you.

Get api latest status

GET /rest/api/latest/status

Returns the current status of the server. This endpoint enables a basic status check on the status of a Bamboo instance.

The status endpoint will be responsive as long as the Bamboo REST plugin will be running. In other words, this endpoint does depend on the instance health and might not answer as a result of a failure or when Bamboo is still starting.

Request

There are no parameters for this request.

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/status' \
  --header 'Accept: application/json'

Responses

200

Returns the current status of the server

Content type	Value
application/json	RestAnonymousServerStatusInfo

Get api latest permissions plan {key} available-users

GET /rest/api/latest/permissions/plan/{key}/available-users

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

Request

Path parameters

key Required

string

Plan entity key

Query parameters

limit

integer

Page request size

Default: 25, Format: int32

start

integer

Page request start index

Format: int32

name

string

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

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/permissions/plan/{key}/available-users' \
  --header 'Accept: application/json'

Responses

200

403

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

Content type	Value
application/json	object

Get api latest permissions plan {key} groups

GET /rest/api/latest/permissions/plan/{key}/groups

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

Path parameters

key Required

string

Plan entity key

Query parameters

limit

integer

Page request size

Default: 25, Format: int32

start

integer

Page request start index

Format: int32

name

string

Group name filter, filter is case insensitive matches group name

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/permissions/plan/{key}/groups' \
  --header 'Accept: application/json'

Responses

200

403

Return single page of groups with their permissions

Content type	Value
application/json	object

Put api latest permissions plan {key} groups {name}

PUT /rest/api/latest/permissions/plan/{key}/groups/{name}

Grants plan permissions to a given group.

Request

Path parameters

name Required

string

Affected group

key Required

string

Plan entity key

Body parameters

Content type	Value
application/json	Array<string>

Example

cURL

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/permissions/plan/{key}/groups/{name}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '[
  "<string>"
]'

Responses

200

304

400

403

404

If permissions were granted

Content type	Value
application/json	anything

Delete api latest permissions plan {key} groups {name}

DELETE /rest/api/latest/permissions/plan/{key}/groups/{name}

Revokes plan permissions from a given group.

Request

Path parameters

name Required

string

Affected group

key Required

string

Plan entity key

Body parameters

Content type	Value
application/json	Array<string>

Example

cURL

Node.js

Java

Python

PHP

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/permissions/plan/{key}/groups/{name}' \
  --header 'Content-Type: application/json' \
  --data '[
  "<string>"
]'

Responses

204

304

400

403

404

If permissions were revoked

Get api latest permissions plan {key} available-groups

GET /rest/api/latest/permissions/plan/{key}/available-groups

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

Request

Path parameters

key Required

string

Plan entity key

Query parameters

limit

integer

Page request size

Default: 25, Format: int32

start

integer

Page request start index

Format: int32

name

string

Group name filter, filter is case insensitive matches group name

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/permissions/plan/{key}/available-groups' \
  --header 'Accept: application/json'

Responses

200

403

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

Content type	Value
application/json	object

Get api latest permissions plan {key} roles

GET /rest/api/latest/permissions/plan/{key}/roles

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.

Request

Path parameters

key Required

string

Plan entity key

Query parameters

limit

integer

Page request size

Default: 25, Format: int32

start

integer

Page request start index

Format: int32

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/permissions/plan/{key}/roles' \
  --header 'Accept: application/json'

Responses

200

403

Return single page of roles with their permissions

Content type	Value
application/json	object

Put api latest permissions plan {key} roles {name}

PUT /rest/api/latest/permissions/plan/{key}/roles/{name}

Grants plan permissions to a given role.

Request

Path parameters

name Required

string

Affected role

key Required

string

Plan entity key

Body parameters

Content type	Value
application/json	Array<string>

Example

cURL

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/permissions/plan/{key}/roles/{name}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '[
  "<string>"
]'

Responses

200

304

400

403

404

If permissions were granted

Content type	Value
application/json	anything

Delete api latest permissions plan {key} roles {name}

DELETE /rest/api/latest/permissions/plan/{key}/roles/{name}

Revokes plan permissions from a given role.

Request

Path parameters

name Required

string

Affected role

key Required

string

Plan entity key

Body parameters

Content type	Value
application/json	Array<string>

Example

cURL

Node.js

Java

Python

PHP

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/permissions/plan/{key}/roles/{name}' \
  --header 'Content-Type: application/json' \
  --data '[
  "<string>"
]'

Responses

204

304

400

403

404

If permissions were revoked

Get api latest permissions plan {key} users

GET /rest/api/latest/permissions/plan/{key}/users

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

Path parameters

key Required

string

Plan entity key

Query parameters

limit

integer

Page request size

Default: 25, Format: int32

start

integer

Page request start index

Format: int32

name

string

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

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/permissions/plan/{key}/users' \
  --header 'Accept: application/json'

Responses

200

403

Return single page of users with their permissions

Content type	Value
application/json	object

Put api latest permissions plan {key} users {name}

PUT /rest/api/latest/permissions/plan/{key}/users/{name}

Grants plan permissions to a given user.

Request

Path parameters

name Required

string

Username of the affected user

key Required

string

Plan entity key

Body parameters

Content type	Value
application/json	Array<string>

Example

cURL

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/permissions/plan/{key}/users/{name}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '[
  "<string>"
]'

Responses

200

304

400

403

404

If permissions were granted

Content type	Value
application/json	anything

Delete api latest permissions plan {key} users {name}

DELETE /rest/api/latest/permissions/plan/{key}/users/{name}

Revokes plan permissions from a given user.

Request

Path parameters

name Required

string

Username of the affected user

key Required

string

Plan entity key

Body parameters

Content type	Value
application/json	Array<string>

Example

cURL

Node.js

Java

Python

PHP

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/permissions/plan/{key}/users/{name}' \
  --header 'Content-Type: application/json' \
  --data '[
  "<string>"
]'

Responses

204

304

400

403

404

If permissions were revoked

Get api latest project {projectKey}

GET /rest/api/latest/project/{projectKey}

Get information for project specified as project key.

plans - list of plans for project
plans.plan - list of plans with plan details (only plans visible - READ permission for user)
plans.plan.actions - list of plans with plan details and actions available for user for plan

Request

Path parameters

projectKey Required

string

project key

Query parameters

expand

string

Possible expand parameters: plans, plans.plan, plans.plan.actions

showEmpty

boolean

flag to return project without plans, true by default

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/project/{projectKey}' \
  --header 'Accept: application/json'

Responses

200

403

404

Project details

Content type	Value
application/json	RestProject

Delete api latest project {projectKey}

DELETE /rest/api/latest/project/{projectKey}

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

Request

Path parameters

projectKey Required

string

project key

Example

cURL

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/project/{projectKey}'

Responses

204

400

403

404

When project is successfully marked for deletion

Get api latest project

GET /rest/api/latest/project

List all projects defined in Bamboo. Projects without any plan are not listed by default, unless showEmpty query param is set to true.

projects - list of projects projects.project - list of projects with project details
projects.project.plans - list of project details and plans for project
projects.project.plans.plan - list of project details and plans for project with plan details

Request

Query parameters

expand

string

Possible expand parameters: projects, projects.project.plans, projects.project.plans.plan

showEmpty

boolean

flag to display projects without plans

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/project' \
  --header 'Accept: application/json'

Responses

200

List of Bamboo projects

Content type	Value
application/json	RestProjects

Post api latest project

POST /rest/api/latest/project

Create project.

Request

Body parameters

Content type	Value
application/xml	RestProject
application/json	RestProject

Example

cURL

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/project' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My first project",
  "key": "PROJ",
  "description": "<string>",
  "publicAccess": true
}'

Responses

201

400

403

Created project

Content type	Value
application/json	RestProject

Get api latest project {projectKey} repositories

GET /rest/api/latest/project/{projectKey}/repositories

Retrieves paginated project repositories specified by the project key.

Request

Path parameters

projectKey Required

string

project key

Query parameters

filter

string

filter to retrieve matching results

limit

integer

Page request size

Default: 25, Maximum: 500, Format: int32

start

integer

Page request start index

Format: int32

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/project/{projectKey}/repositories' \
  --header 'Accept: application/json'

Responses

200

403

404

when repositories were successfully retrieved

Content type	Value
application/json	object

Get api latest project {projectKey} repository

GET /rest/api/latest/project/{projectKey}/repository

Fetch list of repositories which granted to create plan in given project by Repository stored Bamboo Specs.

Request

Path parameters

projectKey Required

string

project key

Example

cURL

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/project/{projectKey}/repository' \
  --header 'Accept: application/json'

Responses

200

403

404

Array of repositories granted to create plan in given project by Repository stored Bamboo Specs

Content type	Value
application/json	Array<RestRepository>

Post api latest project {projectKey} repository

POST /rest/api/latest/project/{projectKey}/repository

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

Request

Path parameters

projectKey Required

string

project key

Body parameters

Content type	Value
application/xml	RestIdContainer
application/json	RestIdContainer

Example

cURL

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/project/{projectKey}/repository' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": 2154
}'

Responses

201

400

403

404

Added repository entity

Content type	Value
application/json	RestRepositoryMinimal

Get api latest project {projectKey} repository search

GET /rest/api/latest/project/{projectKey}/repository/search

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

Request

Path parameters

projectKey Required

string

project key

Query parameters

searchTerm

string

part of repository name. Used to filter output.