Version 2
Version 2.0 represents the latest iteration of the Bitbucket Cloud API. Where possible, you should use the 2.0 APIs rather then the 1.0 version.
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 | |
---|---|---|
Manages repository resources. This endpoint supports the following resources: | ||
Navigate your commits. | ||
Manage the comments and likes associated with pull request comments. | ||
Manage the branches, tags, and manifest associated with a repository. | ||
Manages information related to a team account. | ||
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.
Resource links
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:
$ curl https://api.bitbucket.org/2.0/users/tutorials
{
"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"
}
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:
"self": {
"href": "https://api.bitbucket.org/api/2.0/users/tutorials"
}
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": {
"self": {
"href": "https://api.bitbucket.org/2.0/repositories/evzijst/bitbucket"
},
"clone": [
{
"href": "https://api.bitbucket.org/evzijst/bitbucket.git",
"name": "https"
},
{
"href": "ssh://git@bitbucket.org/erik/bitbucket.git",
"name": "ssh"
}
],
...
}
Links can support URI Templates; Those that do contain a "templated": "true"
element.
Filter and sort API objects
You can query the 2.0 API resources for specific objects using a simple language which resembles SQL.
Supported Endpoints
Several 2.0 API resources that return collections of objects all support a single, shared, generic querying language that is used to filter down a result set.
Currently, the endpoints which support filtering and sorting are:
/2.0/repositories/{username}
/2.0/repositories/{username}/{slug}/refs
/2.0/repositories/{username}/{slug}/refs/branches
/2.0/repositories/{username}/{slug}/refs/tags
/2.0/repositories/{username}/{slug}/forks
/2.0/repositories/{username}/{slug}/issues
/2.0/repositories/{username}/{slug}/pullrequests
Filtering and sorting supports several distinct operators and data types as well as basic features, like logical operators (AND, OR) as shown in the following examples:
(state = "open" OR state = "new") AND assignee = null
reporter.username != "evzijst" AND priority >= "major"
(title ~ "unicode" OR content.raw ~ "unicode") AND created_on > 2015-10-04T14:00:00-07:00
Filter queries can be added to the URL using the q=<query>
query parameter. To sort the response, add sort=<field>
. Note that the entire query string is put in the q
parameter and hence needs to be URL-encoded as shown in the following example:
/2.0/repositories/foo/bar/issues?q=state="new"&sort=-updated_on
Operators
Filtering and sorting supports the following operators:
Operator | Definition | Example |
---|---|---|
"=" | Test for equality | username = "evzijst" |
"!=" | not equal | is_private != true |
"~" | case-insensitive text contains | description ~ "beef" |
"!~" | case-insensitive not contains | description !~ "fubar" |
">" | greater than | priority > "major" |
">=" | greater than or equal | priority <= "trivial" |
"<" | less than | id < 1234 |
"<=" | less than or equal | updated_on <= 2015-03-04 |
Data types
Filtering and sorting supports the following data types:
Type | Description | Example |
---|---|---|
string | any text inside double quotes |
|
number | arbitrary precision integers and floats | 1, -10.302 |
null | to test for the absence of a value | null |
boolean | the unquoted strings true or false | true, false |
datetime | an unquoted ISO-8601 date time string with the timezone offset, milliseconds and entire time component being optional |
Datetime strings are assumed to be in UTC, unless an explicit timezone offset is provided. |
Querying
Objects can be filtered based on their properties. In principle, every element in an object's JSON document can be used as a filter criterion.
Repositories
You can query the following fields in the repository resource:
uuid
(string)full_name
(string)scm
(string)owner
(embedded user object)name
(string)description
(string)created_on
(datetime)updated_on
(datetime)size
(number)language
(string)parent
(embedded repository object)fork_policy
(string)is_private
(boolean)has_issues
(boolean)has_wiki
(boolean)
Fields that contain embedded instances of other object types (e.g. owner
is an embedded user object, while parent
is an embedded repository) can be traversed recursively. For instance:
parent.owner.username = "bitbucket"
Pull Requests
You can query the following fields in the pull request resource:
id
(number)title
(string)description
(string)author
(embedded user object)reviewers
(embedded user object)state
(string)source.repository
(embedded repository object)source.branch.name
(string)destination.repository
(embedded repository object)destination.branch.name
(string)close_source_branch
(boolean)closed_by
(embedded user object)reason
(string)created_on
(datetime)updated_on
(datetime)task_count
(number)comment_count
(number)
For example
To find pull requests which merge into master, come from a fork of the repo rather than a branch inside the repo, and on which I am a reviewer:
source.repository.full_name != "main/repo" AND state = "OPEN" AND reviewers.username = "evzijst" AND destination.branch.name = "master"
/2.0/repositories/main/repo/pullrequests?q=source.repository.full_name+%21%3D+%22main%2Frepo%22+AND+state+%3D+%22OPEN%22+AND+reviewers.username+%3D+%22evzijst%22+AND+destination.branch.name+%3D+%22master%22
Issues
You can query the following fields in the issues resource:
id
(number)title
(string)reporter
(embedded user object)assignee
(embedded user object)content.raw
(string)created_on
(datetime)updated_on
(datetime)state
(string)kind
(string)priority
(string)version
(string)component
(string)milestone
(string)watches
(number)votes
(number)
For example
To find new or on-hold issues related to the UI, created or updated in the last day (SF local time), that have not yet been assigned to anyone:
(state = "new" OR state = "on hold") AND assignee = null AND component = "UI" and updated_on > 2015-11-11T00:00:00-07:00
/2.0/repositories/main/repo/issues?q=%28state+%3D+%22new%22+OR+state+%3D+%22on+hold%22%29+AND+assignee+%3D+null+AND+component+%3D+%22UI%22+and+updated_on+%3E+2015-11-11T00%3A00%3A00-07%3A00
Refs (Branches/Tags/Bookmarks)
You can query the following fields in the refs resource:
name
(string)type
(string)
For example
To find all tags with the string "2015" in the name:
name ~ "2015"
/2.0/repositories/{username}/{slug}/refs/tags?q=name+%7E+%222015%22
Or all my branches and bookmarks:
name ~ "erik/"
/2.0/repositories/{username}/{slug}/refs/tags?q=name+%7E+%22erik%2F%22
Sorting query results
You can sort result sets using the ?sort=<field>
query parameter, available on the same resources that support filtering:
- In principle, every field that can be queried can also be used as a key for sorting.
- By default the sort order is ascending. To reverse the order, prefix the field name with a hyphen (e.g.
?sort=-updated_on
). - Only one field can be sorted on. Compound fields (e.g. sort on
state
first, followed byupdated_on
) are not supported.
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 Cloud's public repositories. Endpoints that return object collections wrap the result in a wrapper object with this structure:
{
"size": 5421,
"page": 2,
"pagelen: 10,
"next": "https://api.bitbucket.org/2.0/repositories/pypy/pypy/commits?page=3",
"previous": "https://api.bitbucket.org/2.0/repositories/pypy/pypy/commits?page=1",
"values": [
...
]
}
The structure's fields have the following values:
Field | Value |
---|---|
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 to 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 |
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 Cloud, list-based responses include the optional size
, page,
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.
{
"error": {
"message": "Bad request",
"fields": {
"src": [
"This field is required."
]
},
"detail": "You must specify a valid source branch when creating a pull request.",
"id": "d23a1cc5178f7637f3d9bf2d13824258"
}
}
This object contains an error element which contains the following nested elements:
Element | Description |
---|---|
message | A short description of the problem. This element is always present. Its value may be localized. |
fields | This 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. |
detail | An optional detailed explanation of the failure. Its value may be localized. |
id | An 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.