REST Resources Provided By: Bitbucket Server - SSH

This is the reference document for the Atlassian Bitbucket REST API. The REST API is for developers who want to:

integrate Bitbucket with other applications;
create scripts that interact with Bitbucket; or
develop plugins that enhance the Bitbucket UI, using REST to interact with the backend.

You can read more about developing Bitbucket plugins in the Bitbucket Developer Documentation.

Getting started

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.

Structure of the REST URIs

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.

Paged APIs

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

Authentication

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.

Errors & Validation

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: were missing from the request; incorrectly formatted; or inappropriate in the given context.
401 (Unauthorized)	Either: Authentication is required but was not attempted. Authentication was attempted but failed. Authentication was successful but the authenticated user does not have the requisite permission for the resource. See the individual resource documentation for details of required permissions.
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: Creating a project with a key that already exists Merging an out-of-date pull request Deleting a comment that has replies etc. See the individual resource documentation for more details.
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.

Personal Repositories

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}/repos

E.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/forks

Using the alternate URL, you would make a GET to:

http://example.com/rest/api/1.0/users/johnsmith/repos/nodejs/forks

Index

Provides SSH support

Resources

Resources

/rest/keys/1.0//projects/{projectKey}/repos/{repositorySlug}/ssh

Methods

GET

/rest/keys/1.0//projects/{projectKey}/repos/{repositorySlug}/ssh?filter&effective&permission

This is a paged API.

Retrieves the access keys for the repository identified in the URL.

request query parameters

parameter value description

filter

string

if specified only SSH access keys with a label prefixed with the supplied string will be returned

effective

boolean

Default: false

Controls whether SSH access keys configured at the project level should be included in the results or not. When set to true all keys that have access to the repository (including project level keys) are included in the results. When set to false, only access keys configured for the specified repository are considered. Default is false.

permission

string

if specified only SSH access keys with at least the supplied permission will be returned Default is Permission.REPO_READ.

Example response representations:

200 - application/json (page) [expand]

Example

{"size":1,"limit":25,"isLastPage":true,"values":[{"key":{"id":1,"text":"ssh-rsa AAAAB3... me@127.0.0.1","label":"me@127.0.0.1"},"repository":{"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"}]}},"permission":"REPO_WRITE"}],"start":0}

A single page of access keys for the repository.

401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions to retrieve the access keys for this repository
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The specified repository does not exist

POST

Example request representations:

application/json [expand]

Example

{"key":{"text":"ssh-rsa AAAAB3... me@127.0.0.1"},"permission":"REPO_WRITE"}

Example response representations:

200 - application/json [expand]

Example

{"key":{"id":1,"text":"ssh-rsa AAAAB3... me@127.0.0.1","label":"me@127.0.0.1"},"repository":{"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"}]}},"permission":"REPO_WRITE"}

The newly created access key

400 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The current request contains invalid or missing values.
401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions to add an access key to the repository
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The specified repository does not exist

/rest/keys/1.0//projects/{projectKey}/repos/{repositorySlug}/ssh/{keyId}

resource-wide template parameters

parameter	value	description
keyId	int	the identifier of the SSH key

Methods

GET

This is a paged API.

Retrieves the access keys for the repository identified in the URL.

Example response representations:

200 - application/json (page) [expand]

Example

{"size":1,"limit":25,"isLastPage":true,"values":[{"key":{"id":1,"text":"ssh-rsa AAAAB3... me@127.0.0.1","label":"me@127.0.0.1"},"repository":{"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"}]}},"permission":"REPO_WRITE"}],"start":0}

A single page of access keys for the repository.

401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions to retrieve the access keys for this repository
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The specified repository does not exist

DELETE

Remove an existing access key for the repository identified in the URL. If the same SSH key is used as an access key for multiple projects or repositories, only the access to the repository identified in the URL will be revoked.

Example response representations:

204 - application/json [expand]
The access key was deleted (or none was found matching the given id).
401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions to remove access keys for this repository

/rest/keys/1.0//ssh/{keyId}/projects

resource-wide template parameters

parameter	value	description
keyId	int

Methods

GET

This is a paged API.

Retrieves all project-related access keys for the SSH key with id keyId. If the current user is not an admin any of the projects the key provides access to, none are returned.

Example response representations:

200 - application/json (page) [expand]
the SSH key with ID keyId.
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The specified key does not exist

/rest/keys/1.0//ssh/{keyId}/repos

resource-wide template parameters

parameter	value	description
keyId	int

Methods

GET

This is a paged API.

Retrieves all repository-related access keys for the SSH key with id keyId. If the current user is not an admin of any of the projects the key provides access to, none are returned.

Example response representations:

200 - application/json (page) [expand]
the SSH key with ID keyId.
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The specified key does not exist

/rest/keys/1.0//projects/{projectKey}/ssh/{keyId}

resource-wide template parameters

parameter	value	description
keyId	int

Methods

DELETE

Remove an existing access key for the project identified in the URL. If the same SSH key is used as an access key for multiple projects or repositories, only the access to the project identified in the URL will be revoked.

Example response representations:

204 - application/json [expand]
The access key was deleted (or none was found matching the given id).
401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions to remove access keys for this project

GET

This is a paged API.

Retrieves the access keys for the project identified in the URL.

Example response representations:

200 - application/json (page) [expand]

Example

{"size":1,"limit":25,"isLastPage":true,"values":[{"key":{"id":1,"text":"ssh-rsa AAAAB3... me@127.0.0.1","label":"me@127.0.0.1"},"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"}]}},"permission":"PROJECT_READ"}],"start":0}

A single page of access keys associated with the project.

401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions to retrieve the access keys for this project
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The specified project does not exist

/rest/keys/1.0//projects/{projectKey}/ssh/{keyId}/permission/{permission}

resource-wide template parameters

parameter	value	description
keyId	int	the SSH key ID
permission	string	the new permission to be granted to the SSH key

Methods

PUT

Updates the permission granted to the specified SSH key to the project identified in the URL.

Example response representations:

200 - application/json [expand]

Example

{"key":{"id":1,"text":"ssh-rsa AAAAB3... me@127.0.0.1","label":"me@127.0.0.1"},"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"}]}},"permission":"PROJECT_READ"}

The newly created access key

401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions on the project to edit its access keys
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The specified project does not exist

/rest/keys/1.0//projects/{projectKey}/repos/{repositorySlug}/ssh/{keyId}/permission/{permission}

resource-wide template parameters

parameter	value	description
keyId	int	the SSH key ID
permission	string	the new permission to be granted to the SSH key

Methods

PUT

Updates the permission granted to the specified SSH key to the project identified in the URL.

Example response representations:

200 - application/json [expand]

Example

{"key":{"id":1,"text":"ssh-rsa AAAAB3... me@127.0.0.1","label":"me@127.0.0.1"},"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"}]}},"permission":"PROJECT_READ"}

The newly created access key

401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions on the project to edit its access keys
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The specified project does not exist

/rest/keys/1.0//projects/{projectKey}/ssh

Methods

POST

Example request representations:

application/json [expand]

Example

{"key":{"text":"ssh-rsa AAAAB3... me@127.0.0.1"},"permission":"PROJECT_READ"}

Example response representations:

200 - application/json [expand]

Example

{"key":{"id":1,"text":"ssh-rsa AAAAB3... me@127.0.0.1","label":"me@127.0.0.1"},"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"}]}},"permission":"PROJECT_READ"}

The newly created access key

400 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The current request contains invalid or missing values.
401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions to add an access key to the project.
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The specified project does not exist

GET

/rest/keys/1.0//projects/{projectKey}/ssh?filter&permission

This is a paged API.

Retrieves the access keys for the project identified in the URL.

request query parameters

parameter	value	description
filter	string	if specified only SSH access keys with a label prefixed with the supplied string will be returned
permission	string	if specified only SSH access keys with at least the supplied permission will be returned Default is {@link Permission#PROJECT_READ}.

Example response representations:

200 - application/json (page) [expand]

Example

{"size":1,"limit":25,"isLastPage":true,"values":[{"key":{"id":1,"text":"ssh-rsa AAAAB3... me@127.0.0.1","label":"me@127.0.0.1"},"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"}]}},"permission":"PROJECT_READ"}],"start":0}

A single page of access keys associated with the project.

401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions to retrieve the access keys for this project
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The specified project does not exist

/rest/keys/1.0//ssh/{keyId}

resource-wide template parameters

parameter	value	description
keyId	int	the identifier of the SSH key

Methods

DELETE

Remove an existing access key for the projects and repositories in the submitted entity. If the same SSH key is used as an access key for multiple projects or repositories not supplied, only the access to the projects or repositories identified will be revoked.

Example request representations:

application/json [expand]

Example response representations:

204 - application/json [expand]
The access keys were deleted (or none was found matching the given id and repositories or projects).
401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions to remove access keys for one or more of the specified projects or repositories
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
On or more of the specified repositories or projects does not exist or the key itself does not exist

/rest/ssh/1.0/keys

Methods

POST

/rest/ssh/1.0/keys?user

Add a new ssh key to a supplied user.

request query parameters

parameter	value	description
user	string	the username of the user to add the ssh key for. If no username is specified, the ssh key will be added for the current authenticated user.

Example request representations:

application/json [expand]
Example
```
{"text":"ssh-rsa AAAAB3... me@127.0.0.1"}
```

Example response representations:

201 - application/json (sshKey) [expand]
Example
```
{"id":1,"text":"ssh-rsa AAAAB3... me@127.0.0.1","label":"me@127.0.0.1"}
```
The newly created ssh key.
400 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The ssh key was not created because the key was not a valid RSA/DSA/ECDSA/Ed25519 key of a supported length.
401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
Either there is no authenticated user or the currently authenticated user has insufficient permissions to add an ssh key. The latter is only possible when a user is explicitly supplied.
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
No user matches the supplied user
409 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The ssh key already exists on the system.

GET

/rest/ssh/1.0/keys?user

This is a paged API.

Retrieve a page of ssh keys.

request query parameters

parameter	value	description
user	string	the username of the user to retrieve the keys for. If no username is specified, the ssh keys will be retrieved for the current authenticated user.

Example response representations:

200 - application/json (page) [expand]

Example

{"size":1,"limit":25,"isLastPage":true,"values":[{"id":1,"text":"ssh-rsa AAAAB3... me@127.0.0.1","label":"me@127.0.0.1"}],"start":0}

A page of ssh keys.

401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions to retrieve the ssh keys. This is only possible when a user is explicitly supplied.
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
No user matches the supplied user

DELETE

/rest/ssh/1.0/keys?user

Delete all ssh keys for a supplied user.

request query parameters

parameter	value	description
user	string	the username of the user to delete the keys for. If no username is specified, the ssh keys will be deleted for the current authenticated user.

Example response representations:

204 [expand]
The ssh keys matching the supplied user were deleted.
401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions to delete the ssh keys. This is only possible when a user is explicitly supplied.
404 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
No user matches the supplied user

/rest/ssh/1.0/keys/{keyId}

resource-wide template parameters

parameter	value	description
keyId	int	the id of the key to delete.

Methods

DELETE

Delete an ssh key.

Example response representations:

204 [expand]
The ssh key matching the supplied id was deleted or did not exist.
401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The currently authenticated user has insufficient permissions to delete the ssh key.

/rest/ssh/1.0/settings

Methods

GET

Example response representations:

200 - application/json [expand]

Example

{"accessKeys":{"enabled":true},"baseUrl":"ssh://example.com","enabled":true,"fingerprint":{"algorithm":"RSA","value":"1BE9A09D47279BF92501DEB9A3D8717D"},"port":7999}

The ssh settings from upstream

401 - application/json (errors) [expand]
Example
```
{"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}
```
The request was not authenticated