Use the Bitbucket Cloud REST APIs
Use our REST API, based on open standards, to build third party applications which can use any web development language to access the API.
Using 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
prefix (for the 2.0 API) and
prefix (1.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.org
Given 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/1.0/repositories/tutorials/tutorials.bitbucket.org/issues
A given endpoint or resource has a series of actions (or methods) associated with it. The Bitbucket service supports these standard HTTP methods:
|Updates existing information.|
|Creates new information.|
|Removes existing information.|
For example, you can call use the
POST action on the
issues resource and create an issue on the issue tracker.
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 -r PUT --header "Content-Length: 0" -u user:pass https://email@example.com
Universally 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's work with both the 1.0 and 2.0 APIs for the user, team, and repository
Call with username:
$ curl https://api.bitbucket.org/2.0/users/tutorials
Call with UUID:
$ curl https://api.bitbucket.org/2.0/users/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7D
Call with team name:
$ curl https://api.bitbucket.org/2.0/teams/1team
Call (for team repositories) with UUID:
$ curl https://api.bitbucket.org/2.0/teams/%7Baa559944-83c9-4963-a9a8-69ac8d9cf5d2%7D
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/moxie
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
There is a 1.0 and 2.0 version of the APIs. The two versions do not encompass the same endpoints or functionality. Currently, you will find that the API 1.0 covers resources that the 2.0 API is yet to cover. Conversely, the 2.0 API has several features that enhance its usability and performance. You should look first to use the 2.0 API whenever possible. The 1.0 APIs are available when the 2.0 does not make the resource you need available.
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.
|Manages a group's repository permissions.|
|Manages groups and their membership.|
|Invite other users to a repository.|
|Manage individual user privileges (permissions) on your repositories|
||Manages repository resources. This endpoint supports the following resources:|
|Manage changesets for a repository.|
|Track events on a public repository.|
|Lists the accounts following a repository.|
|Manage an issue tracker and the issues associated with it.|
|Manage integrations with JIRA, Bamboo, and custom link resources.|
|Manage the comments and likes associated with pull request comments.|
|Manage the branches, tags, and manifest associated with a repository.|
||Manages an account's integrated services.|
|Get information about particular files and directories in a repository.|
Get information about pages in a Wiki.
|Manages the currently authenticated account profile.|
|Manages information related to a specified individual account. This endpoint supports the following resources:|
|Gets information related to an account.|
|Manages the email address associated with an account.|
|Manages the invitations sent by an account.|
|Manages the consumers associated with an account.|
|Manages privilege settings for teams.|
|Manages ssh keys for an account.|
|teams||Retrieves information related to teams.|
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
$ curl --user buserbb:2934dfad https://api.bitbucket.org/1.0/user/repositories
If you are writing an application to integrate with Bitbucket, you should obtain a consumer key and use the OAuth 1.0a framework to authenticate. For a detailed overview regarding OAuth and Bitbucket, see OAuth on Bitbucket Cloud in this documentation.
Was this helpful?
Thanks for your feedback!