REST APIs

robotsnoindex

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.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/2.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:


CallDescription
GETRetrieves information.
PUTUpdates existing information.
POSTCreates new information.
DELETERemoves 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.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 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%7D
See what the response would look like...
{
   "display_name":"tutorials account",
   "uuid":"{c788b2da-b7a2-404c-9e26-d3f077557007}",
   "links":{
      "hooks":{
         "href":"https://api.bitbucket.org/2.0/users/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7D/hooks"
      },
      "self":{
         "href":"https://api.bitbucket.org/2.0/users/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7D"
      },
      "repositories":{
         "href":"https://api.bitbucket.org/2.0/repositories/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7D"
      },
      "html":{
         "href":"https://bitbucket.org/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7D/"
      },
      "avatar":{
         "href":"https://bitbucket.org/account/tutorials/avatar/"
      },
      "snippets":{
         "href":"https://api.bitbucket.org/2.0/snippets/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7D"
      }
   },
   "nickname":"tutorials",
   "created_on":"2011-12-20T16:34:07.132459+00:00",
   "is_staff":false,
   "account_status":"active",
   "type":"user",
   "account_id":null
}


Team

Call for team repositories with UUID:

$ curl https://api.bitbucket.org/2.0/teams/%7Baa559944-83c9-4963-a9a8-69ac8d9cf5d2%7D


Repositories
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


The 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.


EndpointDescription
group-privilegesManages a group's repository permissions.
groupsManages groups and their membership.
invitationsInvite other users to a repository.
users/{accountname}/invitationsGet 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/bbdocs

If 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.

Last modified on Jun 24, 2020

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.