The purpose of this section is to describe how to authenticate when making API calls using the Bitbucket REST API.
Basic HTTP Authentication as per RFC-2617 (Digest not supported). Note that Basic Auth is available only with username and app password as credentials.
Access Tokens are passwords (or tokens) that provide access to a single repository, project or workspace. These tokens can authenticate with Bitbucket APIs for scripting, CI/CD tools, Bitbucket Cloud-connected apps, and Bitbucket Cloud integrations.
Access Tokens are linked to a repository, project, or workspace, not a user account. The level of access provided by the token is set when a repository, or workspace admin creates it, by setting permission scopes.
There are three types of Access Token:
When using Bitbucket APIs with an Access Token, the token will be treated as the "user" in the Bitbucket UI and Bitbucket logs. This includes when using the Access Token to leave a comment on a pull request, push a commit, or merge a pull request. The Bitbucket UI and API responses will show the Repository/Project/Workspace Access Token as a user. The username shown in the Bitbucket UI is the Access Token name, and a custom icon is used to differentiate it from a regular user in the UI.
repository)
and push (repository:write) code to the token's repository or the repositories the token can access.There are some APIs which are inaccessible for Access Tokens, these are:
For details on creating, managing, and using Repository Access Tokens, visit Repository Access Tokens.
The available scopes for Repository Access Tokens are:
repositoryrepository:writerepository:adminrepository:deletepullrequestpullrequest:writewebhookpipelinepipeline:writepipeline:variablerunnerrunner:writeFor details on creating, managing, and using Project Access Tokens, visit Project Access Tokens.
The available scopes for Project Access Tokens are:
projectrepositoryrepository:writerepository:adminrepository:deletepullrequestpullrequest:writewebhookpipelinepipeline:writepipeline:variablerunnerrunner:writeFor details on creating, managing, and using Workspace Access Tokens, visit Workspace Access Tokens.
The available scopes for Workspace Access Tokens are:
projectproject:adminrepositoryrepository:writerepository:adminrepository:deletepullrequestpullrequest:writewebhookaccountpipelinepipeline:writepipeline:variablerunnerrunner:writeApp passwords allow users to make API calls to their Bitbucket account through apps such as Sourcetree.
Some important points about app passwords:
You cannot view an app password or adjust permissions after you create the app password. Because app passwords are encrypted on our database and cannot be viewed by anyone. They are essentially designed to be disposable. If you need to change the scopes or lost the password just create a new one.
You cannot use them to log into your Bitbucket account.
You cannot use app passwords to manage team actions.
App passwords are tied to an individual account's credentials and should not be shared. If you're sharing your app password you're essentially giving direct, authenticated, access to everything that password has been scoped to do with the Bitbucket API's.
You can use them for API call authentication, even if you don't have two-step verification enabled.
You can set permission scopes (specific access rights) for each app password.
For details on creating, managing, and using App passwords, visit App passwords.
Our OAuth 2 implementation is merged in with our existing OAuth 1 in such a way that existing OAuth 1 consumers automatically become valid OAuth 2 clients. The only thing you need to do is edit your existing consumer and configure a callback URL.
Once that is in place, you'll have the following 2 URLs:
1 2https://bitbucket.org/site/oauth2/authorize https://bitbucket.org/site/oauth2/access_token
For obtaining access/bearer tokens, we support three of RFC-6749's grant flows, plus a custom Bitbucket flow for exchanging JWT tokens for access tokens. Note that Resource Owner Password Credentials Grant (4.3) is no longer supported.
The full-blown 3-LO flow. Request authorization from the end user by sending their browser to:
1 2https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=code
The callback includes the ?code={} query parameter that you can swap
for an access token:
1 2$ curl -X POST -u "client_id:secret" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=authorization_code -d code={code}
This flow is useful for browser-based add-ons that operate without server-side backends.
Request the end user for authorization by directing the browser to:
1 2https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=token
That will redirect to your preconfigured callback URL with a fragment
containing the access token
(#access_token={token}&token_type=bearer) where your page's js can
pull it out of the URL.
Somewhat like our existing "2-LO" flow for OAuth 1. Obtain an access token that represents not an end user, but the owner of the client/consumer:
1 2$ curl -X POST -u "client_id:secret" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=client_credentials
If your Atlassian Connect add-on uses JWT authentication, you can swap a JWT for an OAuth access token. The resulting access token represents the account for which the add-on is installed.
Make sure you send the JWT token in the Authorization request header using the "JWT" scheme (case sensitive). Note that this custom scheme makes this different from HTTP Basic Auth (and so you cannot use "curl -u").
1 2$ curl -X POST -H "Authorization: JWT {jwt_token}" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=urn:bitbucket:oauth2:jwt
Once you have an access token, as per RFC-6750, you can use it in a request in any of the following ways (in decreasing order of desirability):
Authorization: Bearer {access_token}access_token={access_token}?access_token={access_token}Since add-ons will not be able to upload their own SSH keys to clone with, access tokens can be used as Basic HTTP Auth credentials to clone securely over HTTPS. This is much like GitHub, yet slightly different:
1 2$ git clone https://x-token-auth:{access_token}@bitbucket.org/user/repo.git
The literal string x-token-auth as a substitute for username is
required (note the difference with GitHub where the actual token is in
the username field).
Our access tokens expire in one hour. When this happens you'll get 401 responses.
Most access tokens grant responses (Implicit and JWT excluded). Therefore, you should include a refresh token that can then be used to generate a new access token, without the need for end user participation:
1 2$ curl -X POST -u "client_id:secret" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=refresh_token -d refresh_token={refresh_token}
Bitbucket's API applies a number of privilege scopes to endpoints. In order to access an endpoint, a request will need to have the necessary scopes.
OAuth 2.0 Scopes are applicable for OAuth 2, Access Tokens, and App passwords auth mechanisms as well as Bitbucket Connect apps.
Scopes are declared in the descriptor as a list of strings, with each string being the name of a unique scope.
A descriptor lacking the scopes element is implicitly assumed to require all scopes and as a result, Bitbucket will require end users authorizing/installing the add-on
to explicitly accept all scopes.
Our best practice suggests you add only the scopes your add-on needs, but no more than it needs.
Invalid scope strings will cause the descriptor to be rejected and the installation to fail.
The available scopes are:
Provides access to view the project or projects.
This scope implies the repository scope, giving read access to all the repositories in a project or projects.
This scope is deprecated, and has been made obsolete by project:admin. Please see the deprecation notice here.
Provides admin access to a project or projects. No distinction is made between public and private projects. This scope doesn't implicitly grant the project scope or the repository:write scope on any repositories under the project. It gives access to the admin features of a project only, not direct access to its repositories' contents.
Provides read access to a repository or repositories. Note that this scope does not give access to a repository's pull requests.
Provides write (not admin) access to a repository or repositories. No distinction is made between public and private repositories. This scope implicitly grants the repository scope, which does not need to be requested separately.
This scope alone does not give access to the pull requests API.
Provides admin access to a repository or repositories. No distinction is made between public and private repositories. This scope doesn't implicitly grant the repository or the repository:write scopes. It gives access to the admin features of a repo only, not direct access to its contents. This scope can be used or misused to grant read access to other users, who can then clone the repo, but users that need to read and write source code would also request explicit read or write.
This scope comes with access to the following functionality:
Provides access to delete a repository or repositories.
Provides read access to pull requests.
This scope implies the repository scope, giving read access to the pull request's destination repository.
Implicitly grants the pullrequest scope and adds the ability to create, merge and decline pull requests.
This scope also implicitly grants the repository:write scope, giving write access to the pull request's destination repository. This is necessary to allow merging.
Ability to interact with issue trackers the way non-repo members can. This scope doesn't implicitly grant any other scopes and doesn't give implicit access to the repository.
This scope implicitly grants the issue scope and adds the ability to transition and delete issues.
This scope doesn't implicitly grant any other scopes and doesn't give implicit access to the repository.
Provides access to wikis. This scope provides both read and write access (wikis are always editable by anyone with access to them). This scope doesn't implicitly grant any other scopes and doesn't give implicit access to the repository.
Gives access to webhooks. This scope is required for any webhook-related operation.
This scope gives read access to existing webhook subscriptions on all resources the authorization mechanism can access, without needing further scopes. For example:
repository scope is not required.issue scope. All that is required is the webhook scope.To create webhooks, the client will need read access to the resource. Such as: for issue:created, the client will need to
have both the webhook and the issue scope.
Provides read access to snippets. No distinction is made between public and private snippets (public snippets are accessible without any form of authentication).
Provides write access to snippets.
No distinction is made between public and private snippets (public snippets are accessible without any form of authentication).
This scope implicitly grants the snippet scope which does not need to be requested separately.
Ability to see the user's primary email address. This should make it easier to use Bitbucket Cloud as a login provider for apps or external applications.
When used for:
Ability to change properties on the user's account.
Gives read-only access to pipelines, steps, deployment environments and variables.
Gives write access to pipelines. This scope allows a user to:
This scope is not needed to trigger a build using a push. Performing a git push (or equivalent actions) will trigger the build. The token doing the push only needs the repository:write scope.
This doesn't give write access to create variables.
Gives write access to create variables in pipelines at the various levels:
Gives read-only access to pipelines runners setup against a workspace or repository.
Gives write access to create/edit/disable/delete pipelines runners setup against a workspace or repository.
In order for a Forge app integration to access Bitbucket API endpoints, it needs to include certain privilege scopes in the app manifest. These are different from Bitbucket OAuth 2.0 scopes.
Unlike OAuth 2.0 scopes, Forge app scopes do not implicitly grant other scopes, for example, write:repository:bitbucket does not implicitly grant read:repository:bitbucket.
Only a subset of Bitbucket API endpoints are currently available for Forge app integrations. These will be labeled with Forge app scopes.
Our best practice suggests you only add the scopes your app needs, but no more than it needs.
The available scopes are:
read:repository:bitbucketwrite:repository:bitbucketadmin:repository:bitbucketdelete:repository:bitbucketread:pullrequest:bitbucketwrite:pullrequest:bitbucketread:project:bitbucketadmin:project:bitbucketread:workspace:bitbucketread:user:bitbucketread:pipeline:bitbucketwrite:pipeline:bitbucketadmin:pipeline:bitbucketread:runner:bitbucketwrite:runner:bitbucketAllows viewing of repository data. Note that this scope does not give access to a repository's pull requests.
Allows modification of repository data. No distinction is made between public and private repositories. This scope does not imply the read:repository:bitbucket scope, so you need to request that separately if required. This scope alone does not give access to the pull request API.
Allows admin activities on repositories. No distinction is made between public and private repositories. This scope does not implicitly grant the read:repository:bitbucket or the write:repository:bitbucket scopes. It gives access to the admin features of a repository only, not direct access to its contents. This scope does not allow modification of repository permissions. This scope comes with access to the following functionality:
Allows deletion of repositories.
Allows viewing of pull requests, plus the ability to comment on pull requests.
This scope does not imply the read:repository:bitbucket scope. With this scope, you could retrieve some data specific to the source/destination repositories of a pull request using pull request endpoints, but it does not give access to repository API endpoints.
Allows the ability to create, update, approve, decline, and merge pull requests.
This scope does not imply the write:repository:bitbucket scope.
Allows viewing of project and project permission data.
Allows the ability to create, update, and delete project. No distinction is made between public and private projects.
This scope does not implicitly grant the read:project:bitbucket scope or any repository scopes. It gives access to the admin features of a project only, not direct access to its repositories' contents.
Allows viewing of workspace and workspace permission data.
Allows viewing of data related to the current user.
Allows read access to all pipeline information (pipelines, steps, caches, artifacts, logs, tests, code-insights).
Allows running pipelines (i.e., start/stop/create pipeline) and uploading tests/code-insights.
This scope does not imply the read:pipeline:bitbucket scope.
Allows admin activities, such as creating pipeline variables.
This scope does not implicitly grant the read:pipeline:bitbucket or the write:pipeline:bitbucket scopes.
Allows viewing of runners information.
Allows runners management.
This scope does not imply the read:runners:bitbucket scope.
You can query the 2.0 API for specific objects using a simple language which resembles SQL.
Note that filtering and querying by username has been deprecated, due to privacy changes. See the announcement for details.
Most 2.0 API resources that return paginated collections of objects support a single, shared, generic querying language that is used to filter down a result set.
This includes, but is in no way limited to:
1 2/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}/src /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 examples, the following queries could be used on the issue tracker endpoint (/2.0/repositories/{workspace}/{slug}/issues/):
1 2(state = "open" OR state = "new") AND assignee = null reporter.nickname != "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=
1 2/2.0/repositories/foo/bar/issues?q=state="new"&sort=-updated_on
Filtering and sorting supports the following operators:
| Operator | Definition | Example |
|---|---|---|
| "=" | test for equality | nickname = "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 |
| "IN" | value present in list | state IN ("OPEN", "MERGED") |
| "NOT IN" | value not present in list | state NOT IN ("DECLINED", "MERGED") |
Filtering and sorting supports the following data types:
| Type | Description | Example |
|---|---|---|
| String | any text inside double quotes | "foo" |
| 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 | 2015-03-04T14:08:59.123+02:00, 2015-03-04T14:08:59 Date time strings are assumed to be in UTC, unless an explicit timezone offset is provided |
| list | a comma separated list of values enclosed in parentheses | ("a", "b"), (1, 2) |
Objects can be filtered based on their properties. In principle, every element in an object's JSON document schema can be used as a filter criterion.
Note that while the array of objects in a paginated response is wrapped in an
envelope with a values element, this prefix should not be included in the
query fields (so use /2.0/repositories/foo/bar/issues?q=state="new", not
/2.0/repositories/foo/bar/issues?q=values.state="new").
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:
1 2parent.owner.nickname = "bitbucket"
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:
1 2source.repository.full_name != "main/repo" AND state = "OPEN" AND reviewers.nickname = "evzijst" AND destination.branch.name = "master"
1 2/2.0/repositories/main/repo/pullrequests?q=source.repository.full_name+%21%3D+%22main%2Frepo%22+AND+state+%3D+%22OPEN%22+AND+reviewers.nickname+%3D+%22evzijst%22+AND+destination.branch.name+%3D+%22master%22
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:
1 2state IN ("new", "on hold") AND assignee = null AND component = "UI" and updated_on > 2015-11-11T00:00:00-07:00
1 2/2.0/repositories/main/repo/issues?q=state%20IN%20%28%22new%22%2C%20%22on%20hold%22%29%20AND%20assignee%20%3D%20null%20AND%20component%20%3D%20%22UI%22%20and%20updated%5Fon%20%3E%202015%2D11%2D11T00%3A00%3A00%2D07%3A00
To find all tags with the string "2015" in the name:
1 2name ~ "2015"
1 2/2.0/repositories/{username}/{slug}/refs/tags?q=name+%7E+%222015%22
Or all my branches:
1 2name ~ "erik/"
1 2/2.0/repositories/{username}/{slug}/refs/?q=name+%7E+%22erik%2F%22
You can sort result sets using the ?sort=
Endpoints that return collections of objects should always apply pagination. Paginated collections are always wrapped in the following wrapper object:
1 2{ "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": [ ... ] }
Pagination is often page-bound, with a query parameter page indicating which page is to be returned.
However, clients are not expected to construct URLs themselves by manipulating the page number query parameter. Instead, the response contains a link to the next page. This link should be treated as an opaque location that is not to be constructed by clients or even assumed to be predictable. The only contract around the next link is that it will return the next chunk of results.
Lack of a next link in the response indicates the end of the collection.
The paginated response contains the following fields:
| 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 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 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.
By default, each endpoint returns the full representation of a resource and in some cases that can be a lot of data. For example, retrieving a list of pull requests can amount to quite a large document.
For better performance, you can ask the server to only return the fields you
really need and to omit unwanted data. To request a partial response and to
add or remove specific fields from a response, use the fields query
parameter.
Most API resources embed a substantial list of links pointing to related resources. This saves the client from constructing its own URLs, but is somewhat wasteful when the client doesn't need them.
To significantly reduce the size of the response, use ?fields=-links:
1 2$ curl https://api.bitbucket.org/2.0/users/evzijst?fields=-links { "nickname": "evzijst", "account_status": "active", "website": "", "display_name": "Erik van Zijst", "uuid": "{a288a0ab-e13b-43f0-a689-c4ef0a249875}", "created_on": "2010-07-07T05:16:36+00:00", "location": null, "type": "user" }
The fields parameter supports 3 modes of operation:
-links)+reviewers)owner.display_name)The fields parameter can contain a list of multiple comma-separated field names
(e.g. fields=owner.display_name,uuid,links.self.href). The parameter itself is
not repeated.
As discussed at Condensed Versus Full Objects,
most objects that are embedded inside other objects (like how owner is an
embedded user object in repository) appear in "condensed" form that omits
many fields. The fields parameter allows us to pull in additional fields in
such cases.
For example, the embedded repository object in a pull request does not normally
contain its owner. To add that in we can use:
+values.destination.repository.owner.
The asterisk can be used to match all fields on a particular level. For
example, removing all entries from the links element can be done like this:
1 2$ curl https://api.bitbucket.org/2.0/users/evzijst?fields=-links.* { "nickname": "evzijst", "account_status": "active", "website": "", "display_name": "Erik van Zijst", "uuid": "{a288a0ab-e13b-43f0-a689-c4ef0a249875}", "links": {}, "created_on": "2010-07-07T05:16:36+00:00", "location": null, "type": "user" }
Wildcards can be used in combination with exclusion and inclusion. For
instance, -*,+foo,+bar will remove all elements from the root level and then
add in foo and bar.
Be aware that when using the +foo.bar syntax in the query string, that the
"+" must be URL encoded as "%2B" and so the URL will be:
1 2https://api.bitbucket.org/2.0/repositories/evzijst/interruptingcow?fields=%2Bowner.created_on
Without URL escaping, "+" is interpreted as an encoded space which will not match any fields.
While a resource's self URL, as well its "collection" URL typically return
the full object with all its fields, there are some exceptions for fields that
are overly verbose or costly to generate.
For instance, a pull request contains the embedded lists of reviewers and
participants. These fields are included from the self URL, but not from the
/pullrequests collections resource, as it would impact performance too much.
To discover any additional fields that might not be included by default,
fields=* can be used.
If we want to get a list of all reviewer nicknames on pull requests I created, we could combine a filter with a partial response. This will omit all other data from the response:
1 2/2.0/repositories/bitbucket/bitbucket/pullrequests?fields=values.id,values.reviewers.nickname,values.state&q=author.uuid%3D%22%7Bd301aafa-d676-4ee0-88be-962be7417567%7D%22 { "values": [ { "reviewers": [ { "nickname": "abhin" }, { "nickname": "dtao" }, { "nickname": "csomme" } ], "state": "OPEN", "id": 11355 }, { "reviewers": [ { "nickname": "csomme" }, { "nickname": "abhin" }, { "nickname": "dstevens" } ], "state": "MERGED", "id": 11347 }, { "reviewers": [ { "nickname": "csomme" }, { "nickname": "jmooring" }, { "nickname": "zdavis" }, { "nickname": "flexbox" } ], "state": "OPEN", "id": 11344 } ] }
Bitbucket uses the Open API Specification (OAI, formerly known as Swagger) to describe its APIs. Our OAI specification schema is hosted at https://api.bitbucket.org/swagger.json and serves as the canonical definition and comprehensive declaration of all available endpoints.
The OAI specification makes writing client applications easier by: auto-generating boilerplate code (like data object classes) and dealing with authentication and error handling.
You can find a comprehensive set of open tools for the OAI specification at: https://github.com/swagger-api.
Bitbucket uses JSON Schema to describe the layout of every type of object
consumed or produced by the API. These schemas are collected under the
#definitions element of our swagger.json file.
When an endpoint expects an object as part of a POST or PUT, it also expects the object to validate against the JSON schemas. The same applies to objects returned by an endpoint.
Most objects in Bitbucket come both in "full" and "partial" representation.
The full representation is when all elements are included. This is the layout
returned by a resource's self location (e.g. /2.0/repositories/foo/bar),
as well as resource collection endpoints (e.g. /2.0/repositories).
However, Bitbucket objects often embed other objects. For example, a repository
object embeds a user object for its owner. Likewise, a pullrequest object
embeds its repository object.
These related objects are embedded, or inlined, to reduce the "chatter" when clients make frequent followup API calls to collect information on common, related information.
Embedded related objects are typically limited in their fields to avoid such object graphs from becoming too deep and noisy. They often exclude their own nested objects in an attempt to strike a balance between performance and utility.
An object's embedded or condensed representation tends to be standardized, meaning the fields included is the same set, regardless of where the object was embedded.
You should be familiar with REST architecture before writing an integration. Read this overview page to gain a good understanding of Bitbucket's REST implementation.
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:
1 2curl 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:
1 2curl 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:
1 2curl -r PUT --header "Content-Length: 0" -u user:app_password https://api.bitbucket.org/1.0/emails/rap@atlassian.com
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's work with both the 1.0 and 2.0 APIs for the user, team, and repository objects. The following examples the following characters are replacements for curly brackets: %7B replaces { and %7D replaces }. You will see this structure in the following example sections.
When you make a call using either the username or the UUID for that user the response is the same.
Call with username:
1 2curl https://api.bitbucket.org/2.0/users/tutorials
*Call with UUID for the user:
1 2curl https://api.bitbucket.org/2.0/users/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7D
Response
1 2{ "username": "tutorials", "nickname": "tutorials", "account_status": "active", "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" }
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.
Call with team name (1team) and repository name (moxie):
1 2curl https://api.bitbucket.org/2.0/repositories/1team/moxie
Call with UUID and empty field:
1 2curl https://api.bitbucket.org/2.0/repositories/%7B%7D/%7B21fa9bf8-b5b2-4891-97ed-d590bad0f871%7D
Call with UUID and teamname:
1 2curl https://api.bitbucket.org/2.0/repositories/1team/%7B21fa9bf8-b5b2-4891-97ed-d590bad0f871%7D
Response
1 2{ "created_on": "2013-11-08T01:11:03.222520+00:00", "description": "", "fork_policy": "allow_forks", "full_name": "1team/moxie", "has_issues": false, "has_wiki": false, "is_private": false, "language": "", "links": { "avatar": { "href": "https://bitbucket.org/1team/moxie/avatar/32/" }, "branches": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/refs/branches" }, "clone": [ { "href": "https://bitbucket.org/1team/moxie.git", "name": "https" }, { "href": "ssh://git@bitbucket.org/1team/moxie.git", "name": "ssh" } ], "commits": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/commits" }, "downloads": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/downloads" }, "forks": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/forks" }, "hooks": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/hooks" }, "html": { "href": "https://bitbucket.org/1team/moxie" }, "pullrequests": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/pullrequests" }, "self": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie" }, "tags": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/refs/tags" }, "watchers": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/watchers" } }, "name": "moxie", "owner": { "display_name": "the team", "links": { "avatar": { "href": "https://bitbucket.org/account/1team/avatar/32/" }, "html": { "href": "https://bitbucket.org/1team/" }, "self": { "href": "https://api.bitbucket.org/2.0/teams/1team" } }, "type": "team", "username": "1team", "uuid": "{aa559944-83c9-4963-a9a8-69ac8d9cf5d2}" }, "project": { "key": "PROJ", "links": { "avatar": { "href": "https://bitbucket.org/account/user/1team/projects/PROJ/avatar/32" }, "html": { "href": "https://bitbucket.org/account/user/1team/projects/PROJ" } }, "name": "Untitled project", "type": "project", "uuid": "{ab52aaeb-16ad-4fb0-bb1d-47e4f00367ff}" }, "scm": "git", "size": 33348, "type": "repository", "updated_on": "2013-11-08T01:11:03.263237+00:00", "uuid": "{21fa9bf8-b5b2-4891-97ed-d590bad0f871}", "website": "" }
This example shows a call for a list of team members using both the team name and with the UUID for the team object. As the call is unauthenticated in the following example the response object will only show members with public profiles. The response is the same in either case.
Call with teamname
1 2curl https://api.bitbucket.org/2.0/teams/1team/members
Call with UUID for team object
1 2curl https://api.bitbucket.org/2.0/teams/%7Baa559944-83c9-4963-a9a8-69ac8d9cf5d2%7D/members
Response
1 2{ "page": 1, "pagelen": 50, "size": 2, "values": [ { "created_on": "2011-12-20T16:34:07.132459+00:00", "display_name": "tutorials account", "links": { "avatar": { "href": "https://bitbucket.org/account/tutorials/avatar/32/" }, "followers": { "href": "https://api.bitbucket.org/2.0/users/tutorials/followers" }, "following": { "href": "https://api.bitbucket.org/2.0/users/tutorials/following" }, "hooks": { "href": "https://api.bitbucket.org/2.0/users/tutorials/hooks" }, "html": { "href": "https://bitbucket.org/tutorials/" }, "repositories": { "href": "https://api.bitbucket.org/2.0/repositories/tutorials" }, "self": { "href": "https://api.bitbucket.org/2.0/users/tutorials" }, "snippets": { "href": "https://api.bitbucket.org/2.0/snippets/tutorials" } }, "location": null, "type": "user", "username": "tutorials", "nickname": "tutorials", "account_status": "active", "uuid": "{c788b2da-b7a2-404c-9e26-d3f077557007}", "website": "https://tutorials.bitbucket.org/" }, { "created_on": "2013-12-10T14:44:13+00:00", "display_name": "Dan Stevens [Atlassian]", "links": { "avatar": { "href": "https://bitbucket.org/account/dans9190/avatar/32/" }, "followers": { "href": "https://api.bitbucket.org/2.0/users/dans9190/followers" }, "following": { "href": "https://api.bitbucket.org/2.0/users/dans9190/following" }, "hooks": { "href": "https://api.bitbucket.org/2.0/users/dans9190/hooks" }, "html": { "href": "https://bitbucket.org/dans9190/" }, "repositories": { "href": "https://api.bitbucket.org/2.0/repositories/dans9190" }, "self": { "href": "https://api.bitbucket.org/2.0/users/dans9190" }, "snippets": { "href": "https://api.bitbucket.org/2.0/snippets/dans9190" } }, "location": null, "type": "user", "username": "dans9190", "nickname": "dans9190", "account_status": "active", "uuid": "{1cd06601-cd0e-4fce-be03-e9ac226978b7}", "website": "" } ] }
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.
1 2{ "type": "error", "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", "data": { "extra": "Optional, endpoint-specific data to further augment the error." } } }
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. |
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.
This section describes Cross-origin resource sharing (CORS), what content types we support in requests and responses, and hyperlinking resources in each json responses.
The Bitbucket API supports Cross-origin resource sharing to allow requests for restricted resources across domains. For more information you can refer to:
Sending a general request from the api to bitbucket.com:
curl -i https://api.bitbucket.org -H "origin: http://bitbucket.com"
Gives this result:
1 2HTTP/1.1 302 FOUND Server: nginx/1.6.2 Vary: Cookie Cache-Control: max-age=900 Content-Type: text/html; charset=utf-8 Strict-Transport-Security: max-age=31536000 Date: Tue, 21 Jun 2016 17:54:37 GMT Location: http://confluence.atlassian.com/x/IYBGDQ X-Served-By: app-110 X-Static-Version: 2c820eb0d2b3 ETag: "d41d8cd98f00b204e9800998ecf8427e" X-Content-Type-Options: nosniff X-Render-Time: 0.00379920005798 Connection: Keep-Alive X-Version: 2c820eb0d2b3 X-Frame-Options: SAMEORIGIN X-Request-Count: 383 X-Cache-Info: cached Content-Length: 0
Sending the same request with the CORS check -X OPTIONS in the call:
curl -i https://api.bitbucket.org -H "origin: http://bitbucket.com" -X OPTIONS
Gives this result:
1 2HTTP/1.1 302 FOUND Server: nginx/1.6.2 Vary: Cookie Cache-Control: max-age=900 Content-Type: text/html; charset=utf-8 Access-Control-Expose-Headers: Accept-Ranges, Content-Encoding, Content-Length, Content-Type, ETag, Last-Modified Strict-Transport-Security: max-age=31536000 Date: Tue, 21 Jun 2016 18:04:30 GMT Access-Control-Max-Age: 86400 Location: http://confluence.atlassian.com/x/IYBGDQ X-Served-By: app-111 Access-Control-Allow-Origin: * X-Static-Version: 2c820eb0d2b3 ETag: "d41d8cd98f00b204e9800998ecf8427e" X-Content-Type-Options: nosniff X-Render-Time: 0.00371098518372 Connection: keep-alive X-Version: 2c820eb0d2b3 X-Frame-Options: SAMEORIGIN X-Request-Count: 357 Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS Access-Control-Allow-Headers: Accept, Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, Origin, Range, X-CsrftokenX-Requested-With X-Cache-Info: not cacheable; request wasn't a GET or HEAD Content-Length: 0
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:
$ curl https://api.bitbucket.org/2.0/users/tutorials
1 2{ "username": "tutorials", "nickname": "tutorials", "account_status": "active", "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:
1 2"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.
1 2"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.
You can use Forge or Atlassian Connect to build apps which can connect with the Bitbucket UI and your own application set. An app could be an integration with another existing service, new features for the Atlassian application, or even a new product that runs within the Atlassian application.
For complete information see: integrating with Bitbucket Cloud
Rate this page: