The Bitbucket REST API allows third-party application developers the means for writing applications for the Bitbucket service. Our REST API is based on open standards, you 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 resources such as an individual (or team) account, repositories, and aspects of these resources such as changesets or comments. 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. | Topics on this page:
|
URI Structure and Methods
All Bitbucket requests start with the https://api.bitbucket.org/1.0 prefix.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/1.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.
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.
| Endpoint | Description | |
|---|---|---|
group-privileges | Manages a group's repository permissions. | |
groups | Manages groups and their membership. | |
invitations | Invite other users to a repository. | |
newuser | Creates a new individual account. | |
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. | |
repo_slug | Manage the branches, tags, and manifest associated with a repository. | |
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 or team 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 team accounts. | |
ssh-keys | Manages ssh keys for an account. | |
Authentication
The Bitbucket 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, administrative data for an account such as the email address requires the caller to either authenticate as the account owner or, in the case of a team account, 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). 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 in this documentation.
Response Codes
To use a REST API, your application makes an HTTP request and parses the response. By default, the response format is JSON. If you wish, you can use the '?format=' query string parameter to override this behavior and receive XML or YAML instead. For example, use following query string to receive output in YAML:
?format=yaml
You can also use the '?callback=' query string parameter with the name of a function to receive a response via JSONP. For example:
?callback=myJSfunc
A Bitbucket response always includes a response header containing one of the following response codes:
| Code | Description |
|---|---|
| 200 OK | Returned on success. For a GET method, the response contains an entity corresponding to the requested resource. For a POST method, the response contains the entity created. |
| 201 CREATED | Returned when a new resource instance is successfully created. |
| 204 NO CONTENT | Returned on successful deletion of a resource instance. |
| 400 BAD REQUEST | Returned if the caller submits a badly formed request. For example, the caller can receive this return if you forget a required parameter. |
| 401 UNAUTHORIZED | Returned if the call requires authentication and either the credentials provided failed or no credentials were provided. |
| 403 FORBIDDEN | Returned if the caller attempts to make a call or modify a resource for which the caller is not authorized. The request was a valid request, the caller's authentication credentials succeeded but those credentials do not grant the caller permission to access the resource. |
| 404 NOT FOUND | Returned if the specified resource does not exist. |
Depending on the call, a response may or may not include a body. Where a body is returned, the individual method documentation shows the expected structure of the returned data in JSON format.
Time zones
Any timestamp returned whose key contains "utc" is in Coordinated Universal Time. All other timestamps are in the local time of Amsterdam. Amsterdam timestamps are now deprecated. If you're using them in your application, please switch to the UTC equivalents.
Labels
Page: OAuth on Bitbucket
Page: oauth Endpoint
Page: groups Endpoint
Page: group-privileges Endpoint
Page: invitations Endpoint
Page: newuser Endpoint
Page: privileges Endpoint
Page: repositories Endpoint
Page: user Endpoint
Page: users Endpoint
8 Comments
Hide/Show CommentsOct 04, 2012
Anthony Steiner
NICE! Someone gave this documentation an overhaul. ME LIKEY!
Oct 25, 2012
Anonymous
The doc says that to list all the private and public repositories I can use this command:
I swap in my username/password and all I get in return is a bunch of html with a title of "Oops, you've found a dead link"
Nov 30, 2012
Mary Anthony [Atlassian]
The proper API is:
https://api.bitbucket.org/1.0/users/buserbb
users Endpoint is what you want.
Jan 01, 2013
Anonymous
I'm also finding that the returned content isn't very helpful. As the default return format is JSON, it should be expected that any errors, dead links (as above), in fact anything, should be returned as JSON.
This returning HTML has been playing havoc with my trying to debug what are required fields and other issues for two days now, as the documentation for this API is very slim.
Would it be possible to please change the responses to follow the format specified, and if no format specified then JSON as per the default? Also could we have some examples of how to actually use this API, like example requests for the different request methods on each end-point?
Jan 01, 2013
Anonymous
Just to clarify, when I get an HTTP 400 the response body (even though the request was JSON) is:
Bad Request <ul class="errorlist"><li>name<ul class="errorlist"><li>You already have a repository with this name.</li></ul></li></ul>
Jan 02, 2013
Mary Anthony [Atlassian]
Hi, I'm sorry to hear you are having problems. You can find examples of how to make requests on each endpoint reference page. You can also use our REST API browser which is a good way to test the calls if you don't want to use CURL.
Yes, the returned HTML is really awkward. You should file a enhancement request regarding the return formats. The devs pay more attention to enhancement requests than doc comments. Maybe because requests are easier to count.
Jan 03, 2013
Anonymous
Thanks for your feedback, I will
Jan 02, 2013
Anthony Steiner
If you're looking for an interim fix, the response header's
Content-Typeproperty would return text/plain upon an error. It should return the mime of the expected format if else;unless you are using JSONP. Then you're pretty much back to square one.Edit: Even JSONP returns a mime other than plain/text.
Add Comment