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.

This page

Related pages

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) and https://api.bitbucket.org/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:

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

 

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/1.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 both the 1.0 and 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 username:

$ curl https://api.bitbucket.org/2.0/users/tutorials
Response from user
{
    "username": "tutorials",
    "website": "https://tutorials.bitbucket.org/",
    "display_name": "tutorials account",
    "uuid": "{c788b2da-b7a2-404c-9e26-d3f077557007}",
    "links": {
        "self": {
            "href": "https://api.bitbucket.org/2.0/users/tutorials"
        },
        "repositories": {
            "href": "https://api.bitbucket.org/2.0/repositories/tutorials"
        },
        "html": {
            "href": "https://bitbucket.org/tutorials"
        },
        "followers": {
            "href": "https://api.bitbucket.org/2.0/users/tutorials/followers"
        },
        "avatar": {
            "href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2013/Nov/25/tutorials-avatar-1563784409-6_avatar.png"
        },
        "following": {
            "href": "https://api.bitbucket.org/2.0/users/tutorials/following"
        }
    },
    "created_on": "2011-12-20T16:34:07.132459+00:00",
    "location": "Santa Monica, CA",
    "type": "user"
}

Call with UUID:

$ curl https://api.bitbucket.org/2.0/users/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7D
Response from UUID call
{
    "username": "tutorials",
    "website": "https://tutorials.bitbucket.org/",
    "display_name": "tutorials account",
    "uuid": "{c788b2da-b7a2-404c-9e26-d3f077557007}",
    "links": {
        "self": {
            "href": "https://api.bitbucket.org/2.0/users/tutorials"
        },
        "repositories": {
            "href": "https://api.bitbucket.org/2.0/repositories/tutorials"
        },
        "html": {
            "href": "https://bitbucket.org/tutorials"
        },
        "followers": {
            "href": "https://api.bitbucket.org/2.0/users/tutorials/followers"
        },
        "avatar": {
            "href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2013/Nov/25/tutorials-avatar-1563784409-6_avatar.png"
        },
        "following": {
            "href": "https://api.bitbucket.org/2.0/users/tutorials/following"
        }
    },
    "created_on": "2011-12-20T16:34:07.132459+00:00",
    "location": "Santa Monica, CA",
    "type": "user"
}

 

Team

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

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
Response from repo
{
    "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 Versions

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.

 

Endpoint Description
            group-privileges
          
Manages a group's repository permissions.
            groups
          
Manages groups and their membership.
            invitations
          
Invite other users to a repository.
            privileges
          
Manage individual user privileges (permissions) on your repositories

repositories











 
Manages repository resources. This endpoint supports the following resources:
            changesets
          
Manage changesets for a repository.
            deploy-keys
          
Manage ssh keys for deploying product builds.
            events
          
Track events on a public repository.
            followers
          
Lists the accounts following a repository.
            issues
          
Manage an issue tracker and the issues associated with it.
            links
          
Manage integrations with JIRA, Bamboo, and custom link resources.
pullrequests
Manage the comments and likes associated with pull request comments.
repository
Manage the branches, tags, and manifest associated with a repository.
services Manages an account's integrated services.
            src
          
Get information about particular files and directories in a repository.
            wiki
          

Get information about pages in a Wiki.

            user
          
Manages the currently authenticated account profile.
users
Manages information related to a specified individual account. This endpoint supports the following resources:
            account
          
Gets information related to an account.
            emails
          
Manages the email address associated with an account.
            invitations
          
Manages the invitations sent by an account.
            oauth
          
Manages the consumers associated with an account.
            privileges
          
Manages privilege settings for teams.
            ssh-keys
          
Manages ssh keys for an account.
teams Retrieves information related to teams.

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

$ 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!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport