Audit
Policies
Branch-utils
Git
Sync
Required-builds
Build-status
Comment-likes
Jira
Mirroring
Branch-permissions
Access-tokens
Insights
Ssh
Api

Rate this page:

About

The Bitbucket Data Center and Server REST API enables you to interact with Bitbucket programmatically. This page documents the REST resources available in Bitbucket, including the HTTP response codes and example requests and responses.

General information about using the REST APIs can be found at Using the REST API and Authenticating with the REST API.

Intro

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

  • integrate &product_name; with other applications;
  • create scripts that interact with Bitbucket Data Center or
  • develop plugins that enhance the Bitbucket Data Center UI, using REST to interact with the backend.

You can read more about developing Bitbucket Data Center plugins in the 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.

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

Structure of the REST URIs

Bitbucket Data Center'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 Data Center REST API uses JSON as its communication format, and the standard HTTP(S) methods like GET, PUT, POST and DELETE. URIs for Bitbucket Data Center'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://bitbucket.example.com

1
2
https://bitbucket.example.com/rest/api/1.0/projects/JIRA/repos/jira/commits

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

Alternatively we also publish a list of resources in https://en.wikipedia.org/wiki/OpenAPI_Specification format. It is available via the triple dot menu above.

Paged APIs

Bitbucket Data Center 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:

1
2
{
    "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:

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

For example:

1
2
    https://bitbucket.example.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