The Bitbucket Cloud REST API

Commit statuses

Commit statuses provide a way to tag commits with meta data, like automated build results.

List commit statuses for a commit

GET /2.0/repositories/{workspace}/{repo_slug}/commit/{commit}/statuses

Returns all statuses (e.g. build results) for a specific commit.

OAuth 2.0 scopes required:

repository

Request

Path parameters

commit Required

string

The commit's SHA1.

repo_slug Required

string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Query parameters

string

Query string to narrow down the response as per filtering and sorting.

sort

string

Field by which the results should be sorted as per filtering and sorting. Defaults to created_on.

Example

cURL

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/commit/{commit}/statuses' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

200

401

404

A paginated list of all commit statuses for this commit.

Content type	Value
application/json	Paginated Commit Statuses

Create a build status for a commit

POST /2.0/repositories/{workspace}/{repo_slug}/commit/{commit}/statuses/build

Creates a new build status against the specified commit.

If the specified key already exists, the existing status object will be overwritten.

Example:

1
2
curl https://api.bitbucket.org/2.0/repositories/my-workspace/my-repo/commit/e10dae226959c2194f2b07b077c07762d93821cf/statuses/build/           -X POST -u jdoe -H 'Content-Type: application/json'           -d '{
    "key": "MY-BUILD",
    "state": "SUCCESSFUL",
    "description": "42 tests passed",
    "url": "https://www.example.org/my-build-result"
  }'

When creating a new commit status, you can use a URI template for the URL. Templates are URLs that contain variable names that Bitbucket will evaluate at runtime whenever the URL is displayed anywhere similar to parameter substitution in Bitbucket Connect. For example, one could use https://foo.com/builds/{repository.full_name} which Bitbucket will turn into https://foo.com/builds/foo/bar at render time. The context variables available are repository and commit.

OAuth 2.0 scopes required:

repository

Request

Path parameters

commit Required

string

The commit's SHA1.

repo_slug Required

string

This can either be the repository slug or the UUID of the repository, surrounded by curly-braces, for example: {repository UUID}.

workspace Required

string

This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example: {workspace UUID}.

Body parameters

Content type	Value
application/json	allOf [object, Commit Status]

Example

cURL

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/commit/{commit}/statuses/build' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "<string>",
  "links": {
    "self": {
      "href": "<string>",
      "name": "<string>"
    },
    "commit": {
      "href": "<string>",
      "name": "<string>"
    }
  },
  "uuid": "<string>",
  "key": "<string>",
  "refname": "<string>",
  "url": "<string>",
  "state": "FAILED",
  "name": "<string>",
  "description": "<string>",
  "created_on": "<string>",
  "updated_on": "<string>"
}'

Responses

201