REST APIs
Bitbucket Cloud REST API version 1 has been removed
Read the deprecation notice for more information, or you can go right to the version 2.0 REST API documentation.
Temporary support for limited 1.0 API resources
The 2.0 REST API will rely on the Atlassian Cloud Admin API for user and group management, but those API endpoints are not yet available. Until the Atlassian platform services are fully available in Bitbucket we will continue to support these 1.0 REST endpoints:
Use our REST API, based on open standards, to build third party applications which can use any web development language to access the API. With the API, users can sign in and grant your application the right to make calls on their behalf. Then, through the API, your application can access Bitbucket Cloud resources such as an individual (or team) account, repositories, and aspects of these resources such as changesets or comments.
Atlassian Connect for Bitbucket Cloud
Interested in building integration's with Bitbucket Cloud?
Now you can build right into the Bitbucket Cloud UI with Atlassian Connect for Bitbucket.
You should be familiar with REST architecture before writing an integration. Good REST resources abound on the Internet. Read this overview page to gain a good understanding of Bitbucket's REST implementation. When you are ready to begin, obtain a consumer key for your application.
URI Structure and Methods
All Bitbucket Cloud requests start with the https://api.bitbucket.org/2.0 prefix (for the 2.0 API). The next segment of the URI path depends on the endpoint of the request. For example, using the curl command and the repositories endpoint you can list all the issues on Bitbucket's tutorial repository:
$ curl https://api.bitbucket.org/2.0/repositories/tutorials/tutorials.bitbucket.orgGiven a specific endpoint, you can then drill down to a particular aspect or resource of that endpoint. The issues resource on a repository is an example:
$ curl https://api.bitbucket.org/2.0/repositories/tutorials/tutorials.bitbucket.org/issuesA given endpoint or resource has a series of actions (or methods) associated with it. The Bitbucket service supports these standard HTTP methods:
| Call | Description |
|---|---|
GET | Retrieves information. |
PUT | Updates existing information. |
POST | Creates new information. |
DELETE | Removes existing information. |
For example, you can call use the POST action on the issues resource and create an issue on the issue tracker.
Specifying Content Length
You can get a 411 Length Required response. If this happens, the API requires a Content-Length header but the client is not sending it. You should add the header yourself, for example using the curl client:
$ curl -r PUT --header "Content-Length: 0" -u user:pass https://api.bitbucket.org/2.0/emails/rap@atlassian.comUniversally Unique Identifier (UUID)
UUID's provide a single point of recognition for users, teams, and repositories. The UUID is distinct from the username, team name, and repository name fields and remains the same even when those fields change. For example when a user changes their username or moves a repository you will need to modify calls which use those identifiers but not if you are pointing to the UUID.
UUID example and structure
UUID's work with 2.0 APIs for the user, team, and repository
In the following examples the following characters are replacements for curly brackets: %7B replaces { and %7D replaces }
User
Call with UUID:
$ curl https://api.bitbucket.org/2.0/users/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7DTeam
Call for team repositories with UUID:
$ curl https://api.bitbucket.org/2.0/teams/%7Baa559944-83c9-4963-a9a8-69ac8d9cf5d2%7DRepositories
Once you have the UUID for a repository you no longer need a username or team name to make the API call so long as you use an empty field. This helps you resolve repositories no matter if the username or team name changes.
With team name (1team) and repository name (moxie):
$ curl https://api.bitbucket.org/2.0/repositories/1team/moxieThe response would look like this:
{
"updated_on": "2013-11-08T01:11:03.263237+00:00",
"size": 33348,
"is_private": false,
"uuid": "{21fa9bf8-b5b2-4891-97ed-d590bad0f871}"
}
With UUID:
With empty field:
$ curl https://api.bitbucket.org/2.0/repositories/%7B%7D/%7B21fa9bf8-b5b2-4891-97ed-d590bad0f871%7D
With team name
$ curl https://api.bitbucket.org/2.0/repositories/1team/%7B21fa9bf8-b5b2-4891-97ed-d590bad0f871%7D
Supported endpoints and their resources
Bitbucket Cloud supports several endpoints. These endpoints may or may not have additional resources. The table below lists the endpoints and their associated resources.
| Endpoint | Description | |
|---|---|---|
group-privileges | Manages a group's repository permissions. | |
groups | Manages groups and their membership. | |
invitations | Invite other users to a repository. | |
users/{accountname}/invitations | Get a list of invitations for a particular account. | |
Authentication
The Bitbucket Cloud API grants access to public data without authentication. Access to private data requires the caller to authenticate under an account with the appropriate access. For example, an account's administrative data, such as the email address, requires the caller to either authenticate as the account owner or, in the case of a team, authenticate as a team member with administrative access to the team. If you are testing an application, you can use a client such as cURL together with basic authentication (username/password, or if you have two-step verification enabled, username/app password).
For example, the following curl call lists the public and private repositories of the bbdocs user:
$ curl --user bbdocs:bbpassword https://api.bitbucket.org/2.0/repositories/bbdocsIf you are writing an application to integrate with Bitbucket, you should obtain a consumer key and use the OAuth 2.0 framework to authenticate. For a detailed overview regarding OAuth and Bitbucket, see OAuth on Bitbucket Cloud in this documentation.