The Bitbucket REST API allows third-party application developers the means for writing applications for the Bitbucket service. Our REST API is based on open standards, you 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 resources such as an individual (or team) account, repositories, and aspects of these resources such as changesets or comments.
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 requests start with the https://bitbucket.org/api/2.0 prefix (for the 2.0 API) and https://bitbucket.org/api/1.0 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:
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:
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.
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 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 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). For example, the following curl call lists the public and private repositories of the
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 in this documentation.