This is the reference document for the Atlassian Bitbucket REST API. The REST API is for developers who want to:
Because the REST API is based on open standards, you can use any web development language or command line tool capable of generating an HTTP request to access the API. See the developer documentation for a basic usage example.
If you're already working with the Atlassian SDK, the REST API Browser is a great tool for exploring and experimenting with the Bitbucket REST API.
Bitbucket's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The Bitbucket REST API uses JSON as its communication format, and the standard HTTP methods like GET, PUT, POST and DELETE. URIs for Bitbucket's REST API resource have the following structure:
http://host:port/context/rest/api-name/api-version/path/to/resource
For example, the following URI would retrieve a page of the latest commits to the jira repository in the JIRA project on https://stash.atlassian.com.
https://stash.atlassian.com/rest/api/1.0/projects/JIRA/repos/jira/commits
See the API descriptions below for a full list of available resources.
Alternatively we also publish a list of resources in WADL format. It is available here.
Bitbucket uses paging to conserve server resources and limit response size for resources that return potentially large
collections of items. A request to a paged API will result in a values
array wrapped in a JSON object
with some paging metadata, like this:
{ "size": 3, "limit": 3, "isLastPage": false, "values": [ { /* result 0 */ }, { /* result 1 */ }, { /* result 2 */ } ], "start": 0, "filter": null, "nextPageStart": 3 }
Clients can use the limit
and start
query parameters to retrieve the desired number of
results.
The limit
parameter indicates how many results to return per page. Most APIs default to returning
25
if the limit is left unspecified. This number can be increased, but note that a resource-specific
hard limit will apply. These hard limits can be configured by server administrators, so it's always best practice to
check the limit
attribute on the response to see what limit has been applied.
The request to get a larger page should look like this:
http://host:port/context/rest/api-name/api-version/path/to/resource?limit={desired size of page}
For example:
https://stash.atlassian.com/rest/api/1.0/projects/JIRA/repos/jira/commits?limit=1000
The start
parameter indicates which item should be used as the first item in the page of results. All
paged responses contain an isLastPage
attribute indicating whether another page of items exists.
Important: If more than one page exists (i.e. the response contains
"isLastPage": false
), the response object will also contain a nextPageStart
attribute
which must be used by the client as the start
parameter on the next request.
Identifiers of adjacent objects in a page may not be contiguous, so the start of the next page is not
necessarily the start of the last page plus the last page's size. A client should always use
nextPageStart
to avoid unexpected results from a paged API.
The request to get a subsequent page should look like this:
http://host:port/context/rest/api-name/api-version/path/to/resource?start={nextPageStart from previous response}
For example:
https://stash.atlassian.com/rest/api/1.0/projects/JIRA/repos/jira/commits?start=25
Any authentication that works against Bitbucket will work against the REST API. The preferred authentication methods are HTTP Basic (when using SSL) and OAuth. Other supported methods include: HTTP Cookies and Trusted Applications.
You can find OAuth code samples in several programming languages at bitbucket.org/atlassian_tutorial/atlassian-oauth-examples.
The log-in page uses cookie-based authentication, so if you are using Bitbucket in a browser you can call REST from JavaScript on the page and rely on the authentication that the browser has established.
If a request fails due to client error, the resource will return an HTTP response code in the 40x range. These can be broadly categorised into:
HTTP Code | Description |
---|---|
400 (Bad Request) |
One or more of the required parameters or attributes:
|
401 (Unauthorized) |
Either:
|
403 (Forbidden) | Actions are usually "forbidden" if they involve breaching the licensed user limit of the server, or degrading the authenticated user's permission level. See the individual resource documentation for more details. |
404 (Not Found) | The entity you are attempting to access, or the project or repository containing it, does not exist. |
405 (Method Not Allowed) | The request HTTP method is not appropriate for the targeted resource. For example an HTTP GET to a resource that only accepts an HTTP POST will result in a 405. |
409 (Conflict) |
The attempted update failed due to some conflict with an existing resource. For example:
|
415 (Unsupported Media Type) |
The request entity has a Content-Type that the server does not support. Almost all of the
Bitbucket REST API accepts application/json format, but check the individual resource
documentation for more details. Additionally, double-check that you are setting the
Content-Type header correctly on your request (e.g. using
-H "Content-Type: application/json" in cURL).
|
For 400 HTTP codes the response will typically contain one or more validation error messages, for example:
{ "errors": [ { "context": "name", "message": "The name should be between 1 and 255 characters.", "exceptionName": null }, { "context": "email", "message": "The email should be a valid email address.", "exceptionName": null } ] }
The context
attribute indicates which parameter or request entity attribute failed validation. Note
that the context
may be null.
For 401, 403, 404 and 409 HTTP codes, the response will contain one or more descriptive error messages:
{ "errors": [ { "context": null, "message": "A detailed error message.", "exceptionName": null } ] }
A 500 (Server Error) HTTP code indicates an incorrect resource url or an unexpected server error. Double-check the URL you are trying to access, then report the issue to your server administrator or Atlassian Support if problems persist.
Bitbucket allows users to manage their own repositories, called personal repositories. These are repositories associated with the user and to which they always have REPO_ADMIN permission.
Accessing personal repositories via REST is achieved through the normal project-centric REST URLs using the user's slug prefixed by tilde as the project key. E.g. to list personal repositories for a user with slug "johnsmith" you would make a GET to:
http://example.com/rest/api/1.0/projects/~johnsmith/repos
In addition to this, Bitbucket allows access to these repositories through an alternate set of user-centric REST URLs beginning with:
http://example.com/rest/api/1.0/users/~{userSlug}/reposE.g. to list the forks of the repository with slug "nodejs" in the personal project of user with slug "johnsmith" using the regular REST URL you would make a GET to:
http://example.com/rest/api/1.0/projects/~johnsmith/repos/nodejs/forksUsing the alternate URL, you would make a GET to:
http://example.com/rest/api/1.0/users/johnsmith/repos/nodejs/forks
Mirroring upstream capability for Bitbucket Server
Sets the mirror specified by a mirror ID as the current user's preferred mirror
Example request representations:
Example response representations:
Retrieves the current user's preferred mirror server
Example response representations:
{"id":"B0F5-CS21-45C2-CCK3","baseUrl":"http://atlassian-vietnam.atlassian.com","name":"Mirror","productType":"Bitbucket","productVersion":"4.0.0","lastSeenDate":1505692658673,"enabled":true}
the preferred mirror server
The user's preferred mirror server could not be found.
Removes the current user's preferred mirror
Example response representations:
an empty response indicating that the user setting has been updated
Example response representations:
{"canCollectAnalytics":true,"serviceEntitlementNumber":"SEN-500"}
The analytics settings from upstream
Authenticates on behalf of a user. Used by mirrors to check the credentials supplied to them by users. If successful a user and their {@link EffectivePermission effective permissions} are returned. Currently only username/password and SSH credentials are supported.
Example request representations:
Example response representations:
{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL","effectivePermissions":[{"permission":"LICENSED_USER"},{"permission":"PROJECT_VIEW","projectId":7},{"permission":"REPO_WRITE","repositoryId":6}]}
The user for the supplied credentials and their {@link EffectivePermission effective permissions}.
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
If the supplied credentials are incomplete or not understood.
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
The currently authenticated user is not permitted to authenticate on behalf of users or authentication with the supplied user credentials failed for some reason
This is a paged API.
Returns a list of mirrors
Example response representations:
{"size":2,"limit":25,"isLastPage":true,"values":[{"id":"B0F5-CS21-45C2-CCK3","baseUrl":"http://atlassian-vietnam.atlassian.com","name":"Mirror","productType":"Bitbucket","productVersion":"4.0.0","lastSeenDate":1505692658673,"enabled":true},{"id":"B08E-RC7D-42H6-9SWU","baseUrl":"http://atlassian-vietnam.atlassian.com","name":"Mirror Vietnam","productType":"Bitbucket","productVersion":"4.0.0","lastSeenDate":1505693234494,"enabled":true}],"start":0}
a page of mirrors
parameter | value | description |
---|---|---|
mirrorId | the ID of the mirror to remove |
Returns the mirror specified by a mirror ID
Example response representations:
{"id":"B0F5-CS21-45C2-CCK3","baseUrl":"http://atlassian-vietnam.atlassian.com","name":"Mirror","productType":"Bitbucket","productVersion":"4.0.0","lastSeenDate":1505692658673,"enabled":true}
the mirror
The mirror could not be found.
Removes a mirror, disabling all access and notifications for the mirror server in question
Example response representations:
an empty response indicating that the mirror has been removed
parameter | value | description |
---|---|---|
mirrorId |
This renders the HTML that is needed to get the remote connect web-panel on the mirror.
Example response representations:
This is a paged API.
Returns a page of repositories enriched with a content hash
Example response representations:
{"size":1,"limit":25,"isLastPage":true,"values":[{"slug":"my-repo","id":1,"name":"My repo","scmId":"git","state":"AVAILABLE","statusMessage":"Available","forkable":true,"project":{"key":"PRJ","id":1,"name":"My Cool Project","description":"The description for my cool project.","public":true,"type":"NORMAL","links":{"self":[{"href":"http://link/to/project"}]}},"public":true,"links":{"clone":[{"href":"ssh://git@<baseURL>/PRJ/my-repo.git","name":"ssh"},{"href":"https://<baseURL>/scm/PRJ/my-repo.git","name":"http"}],"self":[{"href":"http://link/to/repository"}]},"properties":{"contentHash":"b067f7e0-884f-11e5-af63-feff819cdc9f"}}],"start":0}
A page of repositories with content hashes
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
Mirroring is not available
parameter | value | description |
---|---|---|
repoId | the ID of the requested repository |
Returns a repository enriched with a content hash
Example response representations:
{"slug":"my-repo","id":1,"name":"My repo","scmId":"git","state":"AVAILABLE","statusMessage":"Available","forkable":true,"project":{"key":"PRJ","id":1,"name":"My Cool Project","description":"The description for my cool project.","public":true,"type":"NORMAL","links":{"self":[{"href":"http://link/to/project"}]}},"public":true,"links":{"clone":[{"href":"ssh://git@<baseURL>/PRJ/my-repo.git","name":"ssh"},{"href":"https://<baseURL>/scm/PRJ/my-repo.git","name":"http"}],"self":[{"href":"http://link/to/repository"}]},"properties":{"contentHash":"b067f7e0-884f-11e5-af63-feff819cdc9f"}}
The repository with the specified repoId
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
Repository not found
parameter | value | description |
---|---|---|
repoId | the ID of the requested repository |
Returns a page of mirrors for a repository. This resource will return all mirrors along with authorized links to the mirror's repository REST resource. To determine if a repository is available on the mirror, the returned URL needs to be called.
Example response representations:
{"mirrorServer":{"id":"BSERV-1337-ABCD-R2D2-C3P0","baseUrl":"https://us-east.bitbucket.example.com","name":"US East Mirror","productType":"Bitbucket Server","productVersion":"4.2.0","lastSeenDate":1505693291520,"enabled":true},"links":{"self":[{"href":"https://us-east.bitbucket.example.com/rest/mirroring/1.0/repos/1?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ"}]}}
The mirrored repository descriptor
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
Mirroring is not available
This is a paged API.
Retrieves a mirroring request
parameter | value | description |
---|---|---|
state | (optional) the request state to filter on |
Example response representations:
{"size":1,"limit":25,"isLastPage":true,"values":[{"id":1,"addonDescriptorUri":"http://bitbucket-eu.atlassian.com:7990/bitbucket/rest/mirroring/1.0/descriptor","createdDate":1505693291453,"mirrorBaseUrl":"http://bitbucket-eu.atlassian.com:7990/bitbucket","mirrorId":"4f0eb5fc-67fc-48f8-b4a7-87981f026c6a","mirrorName":"Bitbucket Mirror","productType":"Bitbucket","productVersion":"4.0.0","state":"pending"}],"start":0}
A page of mirroring requests
Creates a new mirroring request
Example request representations:
{"addonDescriptorUri":"http://bitbucket-eu.atlassian.com:7990/bitbucket/rest/mirroring/1.0/descriptor","createdDate":1505693291451,"mirrorBaseUrl":"http://bitbucket-eu.atlassian.com:7990/bitbucket","mirrorId":"4f0eb5fc-67fc-48f8-b4a7-87981f026c6a","mirrorName":"Bitbucket Mirror","productType":"Bitbucket","productVersion":"4.0.0","state":"pending"}
Example response representations:
{"id":1,"addonDescriptorUri":"http://bitbucket-eu.atlassian.com:7990/bitbucket/rest/mirroring/1.0/descriptor","createdDate":1505693291453,"mirrorBaseUrl":"http://bitbucket-eu.atlassian.com:7990/bitbucket","mirrorId":"4f0eb5fc-67fc-48f8-b4a7-87981f026c6a","mirrorName":"Bitbucket Mirror","productType":"Bitbucket","productVersion":"4.0.0","state":"pending"}
The created mirroring request
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
The request was invalid or missing
parameter | value | description |
---|---|---|
mirroringRequestId | the ID of the mirroring request to delete |
Retrieves a mirroring request
Example response representations:
{"id":1,"addonDescriptorUri":"http://bitbucket-eu.atlassian.com:7990/bitbucket/rest/mirroring/1.0/descriptor","createdDate":1505693291453,"mirrorBaseUrl":"http://bitbucket-eu.atlassian.com:7990/bitbucket","mirrorId":"4f0eb5fc-67fc-48f8-b4a7-87981f026c6a","mirrorName":"Bitbucket Mirror","productType":"Bitbucket","productVersion":"4.0.0","state":"pending"}
The mirroring request
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
The request could not be found
parameter | value | description |
---|---|---|
mirroringRequestId | the ID of the request to accept |
Accepts a mirroring request
Example response representations:
{"id":"B0F5-CS21-45C2-CCK3","baseUrl":"http://atlassian-vietnam.atlassian.com","name":"Mirror","productType":"Bitbucket","productVersion":"4.0.0","lastSeenDate":1505692658673,"enabled":true}
The accepted mirror server
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
The request could not be found
parameter | value | description |
---|---|---|
mirroringRequestId | the ID of the request to reject |
Rejects a mirroring request
Example response representations:
{"id":1,"addonDescriptorUri":"http://bitbucket-eu.atlassian.com:7990/bitbucket/rest/mirroring/1.0/descriptor","createdDate":1505693291453,"mirrorBaseUrl":"http://bitbucket-eu.atlassian.com:7990/bitbucket","mirrorId":"4f0eb5fc-67fc-48f8-b4a7-87981f026c6a","mirrorName":"Bitbucket Mirror","productType":"Bitbucket","productVersion":"4.0.0","state":"pending"}
The rejected mirroring request
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
The request could not be found