Skip to end of metadata
Go to start of metadata

Version 2.0 represents the latest iteration of the Bitbucket API. Where possible, you should use the 2.0 APIs rather then the 1.0 version.

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.

EndpointDescription

repositories








 
Manages repository resources. This endpoint supports the following resources:

branch-restrictions

 

commit or commits

Navigate your commits.

pullrequests

Manage the comments and likes associated with pull request comments.

repository

Manage the branches, tags, and manifest associated with a repository.

teams

Manages information related to a team account.

users

Manages information related to a user account.

Supported content types

The default and primary content type for 2.0 APIs is JSON. This applies both to responses from the server and to the request bodies provided by the client.  

Unless documented otherwise, whenever creating a new (POST) or modifying an existing (PUT) object, your client must provide the object's normal representation. Not every object element can be mutated. For example, a repository's created_on date is an auto-generated, immutable field. Your client can omit immutable fields from a request body.

In some cases, a resource might also accept regular application/x-www-url-form-encoded POST and PUT bodies. Such bodies can be more convenient in scripts and command line usage. Requests bodies can contain contain nested elements or they can be flat (without nested elements). Clients can send flat request bodies as either as application/json or as application/x-www-url-form-encoded. Nested objects always require JSON.

Every 2.0 object contains a links element that points to related resources or alternate representations. Use links to quickly discover and traverse to related objects. Links serve a "self-documenting" function for each endpoint. For example, the following request for a specific user:

Links can be actual REST API resources or they can be informational. In this example, informative resources include the user's avatar and the HTML URL for the user's Bitbucket account. Your client should avoid hardcoding an API's URL and instead use the URLs returned in API responses. 

A link's key is its rel (relationship) attribute and it contains a mandatory href element. For example, the following link:

The rel for this link is self and the href is https://api.bitbucket.org/api/2.0/users/tutorials. A single rel key can contain an list (array) of href objects. Your client should anticipate that any rel key can contain one or more href objects.

Finally, links can also contain optional elements. Two common optional elements are the name element and the title element. They are often used to disambiguate links that share the same rel key. In the example below, the repository object that contains a clone link with two href objects. Each object contains the optional name element to clarify its use.

Links can support URI Templates; Those that do contain a "templated": "true" element.

Paging through object collections

Many endpoints return object collections. For example, a GET on the https://api.bitbucket.org/2.0/repositories endpoint lists all of Bitbucket's public repositories. Endpoints that return object collections wrap the result in a wrapper object with this structure:

The structure's fields have the following values:

FieldValue
size
Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute.
page
Page number of the current results. This is an optional element that is not provided in all responses.
pagelen
Current number of objects on the existing page. Globally, the minimum length is 10 and the maximum is 100. Some APIs may specify a different default. 
next
Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs.
previous

Link toe previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available.

Use this link to navigate the result set and refrain from constructing your own URLs.

values

The list of objects. This contains at most pagelen objects.

The link to the next page is included such that you don't have to hardcode or construct any links.  Only values and next are guaranteed (except the last page, which lacks next). This is because the previous and size values can be expensive for some data sets. 

It is important to realize that Bitbucket support both list-based pagination and iterator-based pagination. List-based pagination assumes that the collection is a discrete, immutable, consistently ordered, finite array of objects with a fixed size. Clients navigate a list-based collection by requesting offset-based chunks. In Bitbucket, list-based responses include the optional sizepage, and previous element. The the next and previous links typically resemble something like /foo/bar?page=4.

However, not all result sets can be treated as immutable and finite – much like how programming languages tend to distinguish between lists and arrays on one hand and iterators or stream on the other. Where an list-based pagination offers random access into any point in a collection, iterator-based pagination can only navigate forward one element at a time. In Bitbucket such iterator-based pagination contains the next link and pagelen elements, but not necessarily anything else. In these cases, the next link's value often contains an unpredictable hash instead of an explicit page number. The commits resource uses iterator-based pagination.

Standardized error responses

The 2.0 API standardizes the error response layout. The 2.0 API serves a JSON object along with the appropriate HTTP status code. The JSON object provides a detailed  problem description.

This object contains an error element which contains the following nested elements:

ElementDescription
messageA short description of the problem. This element is always present. Its value may be localized.
fieldsThis optional element is used in response to POST or PUT operations in which clients have provided invalid input. It contains a list of one or more client-provided fields that failed validation. The values may be localized.
detailAn optional detailed explanation of the failure. Its value may be localized.
idAn optional unique error identifier that identifies the error in Bitbucket's logging system. If you feel you hit a bug in an API and this field is provided, please mention it if you decide to contact support as it will greatly help us narrow down the problem.

Standard ISO-8601 timestamps

All 2.0 APIs use standardized ISO-8601 timestamps. In most cases, our APIs return UTC timestamps and for these, the timezone offset part will be 00:00. In rare cases where the original localized timestamp has significance, the timezone offset may identify the event's original timezone. An example of this are commit timestamps. These contain the localized value at the committer's original location.

  • No labels

5 Comments

  1. Hi, i just noticed that API1 shows invited projects through /repositories endpoint, but API2 doesnt; 

    Is there any particular reason for that? And when it'll be fixed? 

  2. In Version 1, i can add deploy key and then clone the private repository. But i do not see the deploy key api in Version 2. Is it still under development? or is there any other ways to clone the private repository? maybe clone private repository by using oauth, just like the github does? Thanks.

    1. But i do not see the deploy key api in Version 2. Is it still under development?

      Yes, that is still under development. The v2 API does not yet cover all functionality and most apps will end up using a mixture of v1 and v2 endpoints. Deploy keys is among that.

      maybe clone private repository by using oauth

      Bitbucket uses OAuth 1 (like Twitter) and Git/Mercurial do not support OAuth 1. GitHub uses OAuth 2 which, in contrast to OAuth 1 does not require any special client support which is why you can use it to clone with. So unfortunately that is not an option for you know. You should either use a deploy key over SSH, or username/password over HTTPS.

  3. I am trying to download the full repo as a zip file. I know there is a way to do this if I got to:

    https://bitbucket.org/{owner}/{repo}/downloads

    Then I would manually click on the download for the .zip file. Is there a way to access this zip file from the API directly? If not, can I put in a feature request for this please!

    1. Unfortunately the API currently does not contain links to the download artifacts. However, the URLs are fixed and deterministic and so the direct link to the master branch of a repo is:

      https://bitbucket.org/evzijst/interruptingcow/get/master.zip

      The branch name can be substituted for any tag or SHA1 and the extension can be changed to tgz, bz2 or zip.