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.

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

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

For example:

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

Authentication

Any authentication that works against Bitbucket Data Center 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 HTTP Aaccess Tokens

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

The log-in page uses cookie-based authentication, so if you are using Bitbucket Data Center 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:

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

See the individual resource documentation for

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

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

Provides Rolling Upgrade capabilities.

Table of Contents

• Servers
• Paths
  • GET /state
  • GET /nodes/{nodeId}
  • GET /cluster
  • POST /start
  • POST /cancel
  • POST /approve
• Schemas
  • ClusterStateResponse
  • Link
  • NodeInfoDTO
  • Cluster

Servers

Paths

GET /state

Gets the Cluster State

Gets the State of the Cluster and the responding Node's information.

Responses

▶ 200 - Returns full JSON representation of cluster state

Headers

No headers specified

application/json

Example (generated)

1
2
{
    "state": "STABLE",
    "buildInfo": {
        "id": "string",
        "name": "string",
        "ipAddress": "string",
        "state": "STARTING",
        "tasksTotal": 0,
        "activeUserCount": 0,
        "buildNumber": "string",
        "version": "string",
        "local": true,
        "portNumber": 0,
        "links": [
            {
                "rel": "string",
                "href": "http://example.com"
            }
        ]
    }
}

▶ 401 - Returned if user is not authenticated

Headers

No headers specified

▶ 403 - Returned if the calling user does not have permission to view the content

Headers

No headers specified

Tags

GET /nodes/{nodeId}

Gets the Node's overview

Gets the requested Node's information.

Path parameters

▷ nodeId

Responses

▶ 200 - Returns full JSON representation of the cluster node

Headers

No headers specified

application/json

Example (generated)

1
2
{
    "id": "string",
    "name": "string",
    "ipAddress": "string",
    "state": "STARTING",
    "tasksTotal": 0,
    "activeUserCount": 0,
    "buildNumber": "string",
    "version": "string",
    "local": true,
    "portNumber": 0,
    "links": [
        {
            "rel": "string",
            "href": "http://example.com"
        }
    ]
}

▶ 401 - Returned if user is not authenticated

Headers

No headers specified

▶ 403 - Returned if the calling user does not have permission to view the content

Headers

No headers specified

▶ 404 - Returned if there is no content with the given id

Headers

No headers specified

Tags

GET /cluster

Gets the Cluster overview

Gets an overview of a Cluster including its current state and composition of Nodes.

Responses

▶ 200 - Returns full JSON representation of the cluster

Headers

No headers specified

application/json

Example (generated)

1
2
{
    "upgradeModeEnabled": true,
    "state": "STABLE",
    "originalVersion": "string",
    "nodes": [
        {
            "id": "string",
            "name": "string",
            "ipAddress": "string",
            "state": "STARTING",
            "tasksTotal": 0,
            "activeUserCount": 0,
            "buildNumber": "string",
            "version": "string",
            "local": true,
            "portNumber": 0,
            "links": [
                {
                    "rel": "string",
                    "href": "http://example.com"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "string",
            "href": "http://example.com"
        }
    ]
}

▶ 401 - Returned if user is not authenticated

Headers

No headers specified

▶ 403 - Returned if the calling user does not have permission to view the content

Headers

No headers specified

Tags

POST /start

Start ZDU upgrade

Enables Upgrading of individual Nodes within the Cluster, allowing a heterogeneous Cluster formation.

Responses

▶ 200 - Returns full JSON representation of the cluster

Headers

No headers specified

application/json

Example (generated)

1
2
{
    "upgradeModeEnabled": true,
    "state": "STABLE",
    "originalVersion": "string",
    "nodes": [
        {
            "id": "string",
            "name": "string",
            "ipAddress": "string",
            "state": "STARTING",
            "tasksTotal": 0,
            "activeUserCount": 0,
            "buildNumber": "string",
            "version": "string",
            "local": true,
            "portNumber": 0,
            "links": [
                {
                    "rel": "string",
                    "href": "http://example.com"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "string",
            "href": "http://example.com"
        }
    ]
}

▶ 401 - Returned if user is not authenticated

Headers

No headers specified

▶ 403 - Returned if the calling user does not have permission to view the content

Headers

No headers specified

▶ 409 - Returned if the cluster is not in a valid state

Headers

No headers specified

Tags

POST /cancel

Cancel ZDU upgrade

Prohibits the Upgrading of individual Nodes within the Cluster. All Nodes need to be on the same version before performing this request.

Responses

▶ 200 - Returns full JSON representation of the cluster

Headers

No headers specified

application/json

Example (generated)

1
2
{
    "upgradeModeEnabled": true,
    "state": "STABLE",
    "originalVersion": "string",
    "nodes": [
        {
            "id": "string",
            "name": "string",
            "ipAddress": "string",
            "state": "STARTING",
            "tasksTotal": 0,
            "activeUserCount": 0,
            "buildNumber": "string",
            "version": "string",
            "local": true,
            "portNumber": 0,
            "links": [
                {
                    "rel": "string",
                    "href": "http://example.com"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "string",
            "href": "http://example.com"
        }
    ]
}

▶ 401 - Returned if user is not authenticated

Headers

No headers specified

▶ 403 - Returned if the calling user does not have permission to view the content

Headers

No headers specified

▶ 409 - Returned if the cluster is not in a valid state

Headers

No headers specified

Tags

POST /approve

Approve the ZDU upgrade

Finalizes the ZDU upgrade and runs specific tasks such as cleanup scripts.

Responses

▶ 200 - Returns full JSON representation of the cluster

Headers

No headers specified

application/json

Example (generated)

1
2
{
    "upgradeModeEnabled": true,
    "state": "STABLE",
    "originalVersion": "string",
    "nodes": [
        {
            "id": "string",
            "name": "string",
            "ipAddress": "string",
            "state": "STARTING",
            "tasksTotal": 0,
            "activeUserCount": 0,
            "buildNumber": "string",
            "version": "string",
            "local": true,
            "portNumber": 0,
            "links": [
                {
                    "rel": "string",
                    "href": "http://example.com"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "string",
            "href": "http://example.com"
        }
    ]
}

▶ 401 - Returned if user is not authenticated

Headers

No headers specified

▶ 403 - Returned if the calling user does not have permission to view the content

Headers

No headers specified

▶ 409 - Returned if the cluster is not in a valid state

Headers

No headers specified

▶ 500 - Internal Error

Headers

No headers specified

Tags

Schemas

ClusterStateResponse

Example (generated)

1
2
{
    "state": "STABLE",
    "buildInfo": {
        "id": "string",
        "name": "string",
        "ipAddress": "string",
        "state": "STARTING",
        "tasksTotal": 0,
        "activeUserCount": 0,
        "buildNumber": "string",
        "version": "string",
        "local": true,
        "portNumber": 0,
        "links": [
            {
                "rel": "string",
                "href": "http://example.com"
            }
        ]
    }
}

Link

Example (generated)

1
2
{
    "rel": "string",
    "href": "http://example.com"
}

NodeInfoDTO

Example (generated)

1
2
{
    "id": "string",
    "name": "string",
    "ipAddress": "string",
    "state": "STARTING",
    "tasksTotal": 0,
    "activeUserCount": 0,
    "buildNumber": "string",
    "version": "string",
    "local": true,
    "portNumber": 0,
    "links": [
        {
            "rel": "string",
            "href": "http://example.com"
        }
    ]
}

Cluster

Example (generated)

1
2
{
    "upgradeModeEnabled": true,
    "state": "STABLE",
    "originalVersion": "string",
    "nodes": [
        {
            "id": "string",
            "name": "string",
            "ipAddress": "string",
            "state": "STARTING",
            "tasksTotal": 0,
            "activeUserCount": 0,
            "buildNumber": "string",
            "version": "string",
            "local": true,
            "portNumber": 0,
            "links": [
                {
                    "rel": "string",
                    "href": "http://example.com"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "string",
            "href": "http://example.com"
        }
    ]
}