REST Resources Provided By: Bitbucket Server - Build

This is the reference document for the Atlassian Bitbucket REST API. The REST API is for developers who want to:

You can read more about developing Bitbucket plugins in the Bitbucket Developer Documentation.

Getting started

Because the REST API is based on open standards, you can use any web development language or command line tool capable of generating an HTTP request to access the API. See the developer documentation for a basic usage example.

If you're already working with the Atlassian SDK, the REST API Browser is a great tool for exploring and experimenting with the Bitbucket REST API.

Structure of the REST URIs

Bitbucket'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. The Bitbucket REST API uses JSON as its communication format, and the standard HTTP methods like GET, PUT, POST and DELETE. URIs for Bitbucket's REST API resource have the following structure: 

    http://host:port/context/rest/api-name/api-version/path/to/resource

For example, the following URI would retrieve a page of the latest commits to the jira repository in the Jira project on https://stash.atlassian.com. 

    https://stash.atlassian.com/rest/api/1.0/projects/JIRA/repos/jira/commits

See the API descriptions below for a full list of available resources.

Alternatively we also publish a list of resources in WADL format. It is available here.

Paged APIs

Bitbucket uses paging to conserve server resources and limit response size for resources that return potentially large collections of items. A request to a paged API will result in a values array wrapped in a JSON object with some paging metadata, like this: 

    {
        "size": 3,
        "limit": 3,
        "isLastPage": false,
        "values": [
            { /* result 0 */ },
            { /* result 1 */ },
            { /* result 2 */ }
        ],
        "start": 0,
        "filter": null,
        "nextPageStart": 3
    }

Clients can use the limit and start query parameters to retrieve the desired number of results.

The limit parameter indicates how many results to return per page. Most APIs default to returning 25 if the limit is left unspecified. This number can be increased, but note that a resource-specific hard limit will apply. These hard limits can be configured by server administrators, so it's always best practice to check the limit attribute on the response to see what limit has been applied. The request to get a larger page should look like this: 

    http://host:port/context/rest/api-name/api-version/path/to/resource?limit={desired size of page}

For example: 

    https://stash.atlassian.com/rest/api/1.0/projects/JIRA/repos/jira/commits?limit=1000

The start parameter indicates which item should be used as the first item in the page of results. All paged responses contain an isLastPage attribute indicating whether another page of items exists.

Important: If more than one page exists (i.e. the response contains "isLastPage": false), the response object will also contain a nextPageStart attribute which must be used by the client as the start parameter on the next request. Identifiers of adjacent objects in a page may not be contiguous, so the start of the next page is not necessarily the start of the last page plus the last page's size. A client should always use nextPageStart to avoid unexpected results from a paged API. The request to get a subsequent page should look like this: 

    http://host:port/context/rest/api-name/api-version/path/to/resource?start={nextPageStart from previous response}

For example: 

    https://stash.atlassian.com/rest/api/1.0/projects/JIRA/repos/jira/commits?start=25

Authentication

Any authentication that works against Bitbucket will work against the REST API. The preferred authentication methods are HTTP Basic (when using SSL) and OAuth. Other supported methods include: HTTP Cookies and Trusted Applications.

You can find OAuth code samples in several programming languages at bitbucket.org/atlassian_tutorial/atlassian-oauth-examples.

The log-in page uses cookie-based authentication, so if you are using Bitbucket in a browser you can call REST from JavaScript on the page and rely on the authentication that the browser has established.

Errors & Validation

If a request fails due to client error, the resource will return an HTTP response code in the 40x range. These can be broadly categorised into:

HTTP Code Description
400 (Bad Request) One or more of the required parameters or attributes:
  • were missing from the request;
  • incorrectly formatted; or
  • inappropriate in the given context.
401 (Unauthorized) Either:
  • Authentication is required but was not attempted.
  • Authentication was attempted but failed.
  • Authentication was successful but the authenticated user does not have the requisite permission for the resource.
See the individual resource documentation for details of required permissions.
403 (Forbidden) Actions are usually "forbidden" if they involve breaching the licensed user limit of the server, or degrading the authenticated user's permission level. See the individual resource documentation for more details.
404 (Not Found) The entity you are attempting to access, or the project or repository containing it, does not exist.
405 (Method Not Allowed) The request HTTP method is not appropriate for the targeted resource. For example an HTTP GET to a resource that only accepts an HTTP POST will result in a 405.
409 (Conflict) The attempted update failed due to some conflict with an existing resource. For example:
  • Creating a project with a key that already exists
  • Merging an out-of-date pull request
  • Deleting a comment that has replies
  • etc.
See the individual resource documentation for more details.
415 (Unsupported Media Type) The request entity has a Content-Type that the server does not support. Almost all of the Bitbucket REST API accepts application/json format, but check the individual resource documentation for more details. Additionally, double-check that you are setting the Content-Type header correctly on your request (e.g. using -H "Content-Type: application/json" in cURL).

For 400 HTTP codes the response will typically contain one or more validation error messages, for example: 

    {
        "errors": [
            {
                "context": "name",
                "message": "The name should be between 1 and 255 characters.",
                "exceptionName": null
            },
            {
                "context": "email",
                "message": "The email should be a valid email address.",
                "exceptionName": null
            }
        ]
    }

The context attribute indicates which parameter or request entity attribute failed validation. Note that the context may be null.

For 401, 403, 404 and 409 HTTP codes, the response will contain one or more descriptive error messages: 

    {
        "errors": [
            {
                "context": null,
                "message": "A detailed error message.",
                "exceptionName": null
            }
        ]
    }

A 500 (Server Error) HTTP code indicates an incorrect resource url or an unexpected server error. Double-check the URL you are trying to access, then report the issue to your server administrator or Atlassian Support if problems persist.

Personal Repositories

Bitbucket allows users to manage their own repositories, called personal repositories. These are repositories associated with the user and to which they always have REPO_ADMIN permission.

Accessing personal repositories via REST is achieved through the normal project-centric REST URLs using the user's slug prefixed by tilde as the project key. E.g. to list personal repositories for a user with slug "johnsmith" you would make a GET to: 

http://example.com/rest/api/1.0/projects/~johnsmith/repos

In addition to this, Bitbucket allows access to these repositories through an alternate set of user-centric REST URLs beginning with: 

http://example.com/rest/api/1.0/users/~{userSlug}/repos
E.g. to list the forks of the repository with slug "nodejs" in the personal project of user with slug "johnsmith" using the regular REST URL you would make a GET to: 
http://example.com/rest/api/1.0/projects/~johnsmith/repos/nodejs/forks
Using the alternate URL, you would make a GET to: 
http://example.com/rest/api/1.0/users/johnsmith/repos/nodejs/forks

Index

Provides support for tracking build results and required build merge check

Resources

/rest/build-status/1.0/commits/stats/{commitId}

resource-wide template parameters
parametervaluedescription

commitId

string

full SHA1 of the commit (ex: e00cf62997a027bbf785614a93e2e55bb331d268)

Methods

GET

/rest/build-status/1.0/commits/stats/{commitId}?includeUnique

Gets statistics regarding the builds associated with a commit.

request query parameters
parametervaluedescription

includeUnique

boolean

Default: false

include a unique build result if there is either only one failed build, only one in-progress build or only one successful build

Example response representations:

  • 200 - application/json [expand]

    Example
    {"successful":3,"inProgress":0,"failed":1}

    The number of successful/failed/in-progress builds for the commit

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"You are not permitted to access this resource","exceptionName":null}]}

    The user is not authenticated or does not have the LICENSED permission.

/rest/build-status/1.0/commits/{commitId}

resource-wide template parameters
parametervaluedescription

commitId

string

full SHA1 of the commit (ex: e00cf62997a027bbf785614a93e2e55bb331d268)

Methods

GET

/rest/build-status/1.0/commits/{commitId}?orderBy

Gets the build statuses associated with a commit.

request query parameters
parametervaluedescription

orderBy

string

Default: newest

how the results should be ordered. Options are NEWEST, OLDEST, STATUS. Defaults to NEWEST if not provided.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"state":"SUCCESSFUL","key":"REPO-MASTER","name":"REPO-MASTER-42","url":"https://bamboo.example.com/browse/REPO-MASTER-42","description":"Changes by John Doe","dateAdded":1642747707424}],"start":0}

    a page of build statuses associated with the commit (limited to the most recent 100 build statuses associated with the commit)

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"You are not permitted to access this resource","exceptionName":null}]}

    The user is not authenticated or does not have the LICENSED permission.

POST

Associates a build status with a commit.

The state, the key and the url are mandatory. The name and description fields are optional.

All fields (mandatory or optional) are limited to 255 characters, except for the url, which is limited to 450 characters.

Supported values for the state are SUCCESSFUL, FAILED and INPROGRESS.

The authenticated user must have LICENSED permission or higher to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"state":"SUCCESSFUL","key":"REPO-MASTER","name":"REPO-MASTER-42","url":"https://bamboo.example.com/browse/REPO-MASTER-42","description":"Changes by John Doe"}

Example response representations:

  • 204 [expand]

    An empty response if the build status was successfully stored

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

    Example
    {"errors":[{"context":null,"message":"Please specify a non-blank key","exceptionName":null}]}

    An error message if the commitId if not a full 40-characters SHA1, if the build status has a missing mandatory field or if the fields are too large

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"You are not permitted to access this resource","exceptionName":null}]}

    The user is not authenticated or does not have the LICENSED permission.

/rest/build-status/1.0/commits/stats

Methods

POST

Produces a list of the build statistics for multiple commits.

Commits without any builds associated with them will not be returned. For example if the commit e00cf62997a027bbf785614a93e2e55bb331d268 does not have any build statuses associated with it, it will not be present in the response.

Example request representations:

  • application/json [expand]

    Example
    ["db0dd118fa6ccdf1d593fef00df839dd27702df7","99e9634a6d1dbb2e0c12d7c22aad6c0f66f1c489","6f6cf2f1afa443b03de1e586ee6ece98f4b46633","29357b5a57a0a1149dc5e7761fd89b02d22353c4","056b647404c611003fe260e9766cd5facfdc7b3a","c2d9e5b9e07f90bf584b2f5aeceed5a78c68a7ce","bde37280e62fcc2b1151b50fe91f387d1e84abee","dc56b0f2ce65245fa8ddd67711765a915602541f","290998570c81dfc4c2d9152391ecfe2b752ac8c8","a464d845c05da15fec9d5580715ada7af56b8772","4d0cfc66f56e05cc86127a4e5e1a88c32c689af8"]

Example response representations:

  • 200 - application/json [expand]

    Example
    {"db0dd118fa6ccdf1d593fef00df839dd27702df7":{"successful":3,"inProgress":0,"failed":1},"bde37280e62fcc2b1151b50fe91f387d1e84abee":{"successful":0,"inProgress":1,"failed":1},"4d0cfc66f56e05cc86127a4e5e1a88c32c689af8":{"successful":2,"inProgress":0,"failed":0}}

    The number of successful/failed/in-progress builds for each commit (with the caveat that the commits without any builds associated with them will not be present in the response)

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"You are not permitted to access this resource","exceptionName":null}]}

    The user is not authenticated or does not have the LICENSED permission.

/rest/required-builds/1.0/projects/{projectKey}/repos/{repositorySlug}/conditions

Methods

GET

Returns a page of required build merge checks that have been configured for this repository

The authenticated user must have REPO_READ permission for the target repository to request a page of required build merge checks.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"id":42,"buildParentKeys":["EXAMPLE-PROJECT"],"refMatcher":{"id":"refs/heads/NONE-**","displayId":"NONE-**","type":{"id":"PATTERN","name":"Pattern"},"active":true},"exemptRefMatcher":{"id":"refs/heads/develop","displayId":"develop","type":{"id":"BRANCH","name":"Branch"},"active":true}}],"start":0}

    The required build merge checks associated with the provided repository

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"You are not permitted to access this resource","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to request a page of required build merge checks in this repository

/rest/required-builds/1.0/projects/{projectKey}/repos/{repositorySlug}/condition/{id}

resource-wide template parameters
parametervaluedescription

id

long

The id of the required build merge check

Methods

PUT

Update the required builds merge check for the given ID.

The authenticated user must have REPO_ADMIN permission for the target repository to request a page of required build merge checks.

Example request representations:

  • */* [expand]

    Example
    {"buildParentKeys":["EXAMPLE-PROJECT"],"refMatcher":{"id":"refs/heads/NONE-**","displayId":"NONE-**","type":{"id":"PATTERN","name":"Pattern"},"active":true},"exemptRefMatcher":{"id":"refs/heads/develop","displayId":"develop","type":{"id":"BRANCH","name":"Branch"},"active":true}}

Example response representations:

  • 200 - application/json [expand]

    Example
    {"id":42,"buildParentKeys":["EXAMPLE-PROJECT"],"refMatcher":{"id":"refs/heads/NONE-**","displayId":"NONE-**","type":{"id":"PATTERN","name":"Pattern"},"active":true},"exemptRefMatcher":{"id":"refs/heads/develop","displayId":"develop","type":{"id":"BRANCH","name":"Branch"},"active":true}}

    A response indicating the updated required build merge check

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

    Example
    {"errors":[{"context":null,"message":"The field 'refMatcher' must contain a valid ref matcher","exceptionName":null}]}

    The request was malformed. This could be caused because:

    • The build parent key list is empty
    • Either of the provided ref matchers is of an unrecognized type
    • Either of the provided ref matchers could not be created with the provided type and id

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"You are not permitted to access this resource","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update a required build merge check in this repository

DELETE

Deletes a required build existing merge check, given it's ID.

The authenticated user must have REPO_ADMIN permission for the target repository to delete a required build merge check.

Example response representations:

  • 204 [expand]

    an empty response indicating the merge check was successfully deleted, or was never present

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"You are not permitted to access this resource","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to delete a required build merge check in this repository

/rest/required-builds/1.0/projects/{projectKey}/repos/{repositorySlug}/condition

Methods

POST

Create a required build merge check for the given repository.

The authenticated user must have REPO_ADMIN permission for the target repository to register a required build merge check.

Example request representations:

  • */* [expand]

    Example
    {"buildParentKeys":["EXAMPLE-PROJECT"],"refMatcher":{"id":"refs/heads/NONE-**","displayId":"NONE-**","type":{"id":"PATTERN","name":"Pattern"},"active":true},"exemptRefMatcher":{"id":"refs/heads/develop","displayId":"develop","type":{"id":"BRANCH","name":"Branch"},"active":true}}

Example response representations:

  • 200 - application/json [expand]

    Example
    {"id":42,"buildParentKeys":["EXAMPLE-PROJECT"],"refMatcher":{"id":"refs/heads/NONE-**","displayId":"NONE-**","type":{"id":"PATTERN","name":"Pattern"},"active":true},"exemptRefMatcher":{"id":"refs/heads/develop","displayId":"develop","type":{"id":"BRANCH","name":"Branch"},"active":true}}

    A response containing the newly created required build merge check

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

    Example
    {"errors":[{"context":null,"message":"The field 'refMatcher' must contain a valid ref matcher","exceptionName":null}]}

    The request was malformed. This could be caused because:

    • The build parent key list is empty
    • Either of the provided ref matchers is of an unrecognized type
    • Either of the provided ref matchers could not be created with the provided type and id

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"You are not permitted to access this resource","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to create a required build merge check in this repository