REST Resources Provided By: Bitbucket Server - Ref Restriction
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 the ability to apply ref restrictions to enforce branch permissions
Resources
/rest/branch-permissions/2.0/projects/{projectKey}/repos/{repositorySlug}/restrictions
Methods
GET
/rest/branch-permissions/2.0/projects/{projectKey}/repos/{repositorySlug}/restrictions?type&matcherType&matcherId
This is a paged API.
Search for restrictions using the supplied parameters.
The authenticated user must have REPO_ADMIN permission or higher to call this resource.
Only authenticated users may call this resource.
request query parameters
| parameter | value | description |
|---|
type | string | (optional) types of restrictions to filter on: one of 'read-only', 'no-deletes', 'fast-forward-only' or 'pull-request-only'. |
matcherType | string | (optional) matcher type to filter on: one of 'BRANCH', 'PATTERN', 'MODEL_CATEGORY' or 'MODEL_BRANCH'. |
matcherId | string | (optional) matcher id to filter on. Requires the matcherType parameter to be specified also. |
Example response representations:
Example
{
"size": 2,
"limit": 25,
"isLastPage": true,
"values": [
{
"id": 2,
"scope": {
"resourceId": 2,
"type": "REPOSITORY"
},
"type": "READ_ONLY",
"matcher": null,
"users": [
{
"name": "jcitizen",
"emailAddress": "jane@example.com",
"id": 101,
"displayName": "Jane Citizen",
"active": true,
"slug": "jcitizen",
"type": "NORMAL"
}
],
"groups": [
"bitbucket-users"
],
"accessKeys": [
{
"key": {
"id": 1,
"text": "ssh-rsa AAAAAA... me@atlassian.com",
"label": "me@atlassian.com"
}
}
]
},
{
"id": 2,
"scope": {
"resourceId": 2,
"type": "REPOSITORY"
},
"type": "PULL_REQUEST_ONLY",
"matcher": null,
"users": [],
"groups": [],
"accessKeys": []
}
],
"start": 1
}
404 - application/json (not-found)
[
expand]
The restriction could not be found.
POST
Allows creating multiple restrictions at once.
Example request representations:
application/vnd.atl.bitbucket.bulk+json
[
expand]
Example
[
{
"type": "read-only",
"matcher": {
"id": "refs/tags/**",
"displayId": "refs/tags/**",
"type": {
"id": "PATTERN",
"name": "Pattern"
},
"active": true
},
"users": [
"bman",
"tstark",
"hulk"
],
"groups": [
"bitbucket-users"
],
"accessKeys": [
1,
2,
3
]
},
{
"type": "read-only",
"matcher": {
"id": "refs/heads/**",
"displayId": "refs/heads/**",
"type": {
"id": "PATTERN",
"name": "Pattern"
},
"active": true
},
"users": [
"bman",
"tstark",
"hulk"
],
"groups": [
"bitbucket-developers"
],
"accessKeys": []
}
]
Example response representations:
200 - application/json (restriction)
[
expand]
Example
[
{
"id": 2,
"scope": {
"resourceId": 2,
"type": "REPOSITORY"
},
"type": "READ_ONLY",
"matcher": null,
"users": [
{
"name": "jcitizen",
"emailAddress": "jane@example.com",
"id": 101,
"displayName": "Jane Citizen",
"active": true,
"slug": "jcitizen",
"type": "NORMAL"
}
],
"groups": [
"bitbucket-users"
],
"accessKeys": [
{
"key": {
"id": 1,
"text": "ssh-rsa AAAAAA... me@atlassian.com",
"label": "me@atlassian.com"
}
}
]
}
]
Response contains the ref restrictions that were just created.
Example
{
"errors": [
{
"context": "field_a",
"message": "A detailed validation error message for field_a.",
"exceptionName": null
},
{
"context": null,
"message": "A detailed error message.",
"exceptionName": null
}
]
}
The request has failed validation.
401 - application/json (validation)
[
expand]
Example
{
"errors": [
{
"context": null,
"message": "A detailed error message.",
"exceptionName": null
}
]
}
The currently authenticated user has insufficient permissions to perform this operation.
POST
Create a restriction for the supplied branch or set of branches to be applied to the given repository.
A restriction means preventing writes on the specified branch(es) by all except a set of users and/or groups, or preventing specific
operations such as branch deletion.
For example, you can restrict write access on 'master' to just the 'senior-developer' group, or prevent anyone from deleting that branch.
The request matcher and type must conform to the following.
- The matcher can be one of the following types
-
'BRANCH' represents a specific Branch name. You must supply the fully qualified name of the ref to restrict, e.g. "refs/heads/master"
instead of "master".
-
'PATTERN' represents a wildcard pattern that may match multiple branches. You must specify a valid
Branch Permission Pattern.
-
'MODEL_CATEGORY' represents Branch prefixes in the Branching model for the repository. The 'id' must be one of
- 'FEATURE'
- 'BUGFIX'
- 'HOTFIX'
- 'RELEASE'
See the Branch REST API for more information.
-
'MODEL_BRANCH' represents either the Development or Production branch in the branching model for the repository. The 'id' must be one of
- 'development'
- 'production'
See the Branch REST API for more information.
- Type: Set and be one of
- 'pull-request-only'
- 'fast-forward-only'
- 'no-deletes'
- 'read-only'
The authenticated user must have REPO_ADMIN permission or higher
to call this resource.
Only authenticated users may call this resource.
Example request representations:
Example
{
"type": "read-only",
"matcher": {
"id": "refs/tags/**",
"displayId": "refs/tags/**",
"type": {
"id": "PATTERN",
"name": "Pattern"
},
"active": true
},
"users": [
"bman",
"tstark",
"hulk"
],
"groups": [
"bitbucket-users"
],
"accessKeys": [
1,
2,
3
]
}
Example response representations:
200 - application/json (restriction)
[
expand]
Example
{
"id": 2,
"scope": {
"resourceId": 2,
"type": "REPOSITORY"
},
"type": "READ_ONLY",
"matcher": null,
"users": [
{
"name": "jcitizen",
"emailAddress": "jane@example.com",
"id": 101,
"displayName": "Jane Citizen",
"active": true,
"slug": "jcitizen",
"type": "NORMAL"
}
],
"groups": [
"bitbucket-users"
],
"accessKeys": [
{
"key": {
"id": 1,
"text": "ssh-rsa AAAAAA... me@atlassian.com",
"label": "me@atlassian.com"
}
}
]
}
Response contains the ref restriction that was just created.
Example
{
"errors": [
{
"context": "field_a",
"message": "A detailed validation error message for field_a.",
"exceptionName": null
},
{
"context": null,
"message": "A detailed error message.",
"exceptionName": null
}
]
}
The request has failed validation.
401 - application/json (validation)
[
expand]
Example
{
"errors": [
{
"context": null,
"message": "A detailed error message.",
"exceptionName": null
}
]
}
The currently authenticated user has insufficient permissions to perform this operation.
/rest/branch-permissions/2.0/projects/{projectKey}/repos/{repositorySlug}/restrictions/{id}
resource-wide template parameters
| parameter | value | description |
|---|
id | int | |
Methods
DELETE
Deletes a restriction as specified by a restriction id.
The authenticated user must have REPO_ADMIN permission or higher
to call this resource.
Only authenticated users may call this resource.
Example response representations:
an empty response indicating that the restriction no longer exists on the repository
GET
Returns a restriction as specified by a restriction id.
The authenticated user must have REPO_ADMIN permission or higher
to call this resource.
Only authenticated users may call this resource.
Example response representations:
200 - application/json (restriction)
[
expand]
Example
{
"id": 2,
"scope": {
"resourceId": 2,
"type": "REPOSITORY"
},
"type": "READ_ONLY",
"matcher": null,
"users": [
{
"name": "jcitizen",
"emailAddress": "jane@example.com",
"id": 101,
"displayName": "Jane Citizen",
"active": true,
"slug": "jcitizen",
"type": "NORMAL"
}
],
"groups": [
"bitbucket-users"
],
"accessKeys": [
{
"key": {
"id": 1,
"text": "ssh-rsa AAAAAA... me@atlassian.com",
"label": "me@atlassian.com"
}
}
]
}
The restriction that was created
The restriction could not be found.
/rest/branch-permissions/2.0/projects/{projectKey}/restrictions
Methods
GET
/rest/branch-permissions/2.0/projects/{projectKey}/restrictions?type&matcherType&matcherId
This is a paged API.
Search for restrictions using the supplied parameters.
The authenticated user must have REPO_ADMIN permission or higher to call this resource.
Only authenticated users may call this resource.
request query parameters
| parameter | value | description |
|---|
type | string | (optional) types of restrictions to filter on: one of 'read-only', 'no-deletes', 'fast-forward-only' or 'pull-request-only'. |
matcherType | string | (optional) matcher type to filter on: one of 'BRANCH', 'PATTERN', 'MODEL_CATEGORY' or 'MODEL_BRANCH'. |
matcherId | string | (optional) matcher id to filter on. Requires the matcherType parameter to be specified also. |
Example response representations:
Example
{
"size": 2,
"limit": 25,
"isLastPage": true,
"values": [
{
"id": 2,
"scope": {
"resourceId": 2,
"type": "REPOSITORY"
},
"type": "READ_ONLY",
"matcher": null,
"users": [
{
"name": "jcitizen",
"emailAddress": "jane@example.com",
"id": 101,
"displayName": "Jane Citizen",
"active": true,
"slug": "jcitizen",
"type": "NORMAL"
}
],
"groups": [
"bitbucket-users"
],
"accessKeys": [
{
"key": {
"id": 1,
"text": "ssh-rsa AAAAAA... me@atlassian.com",
"label": "me@atlassian.com"
}
}
]
},
{
"id": 2,
"scope": {
"resourceId": 2,
"type": "REPOSITORY"
},
"type": "PULL_REQUEST_ONLY",
"matcher": null,
"users": [],
"groups": [],
"accessKeys": []
}
],
"start": 1
}
404 - application/json (not-found)
[
expand]
The restriction could not be found.
POST
Allows creating multiple restrictions at once.
Example request representations:
application/vnd.atl.bitbucket.bulk+json
[
expand]
Example
[
{
"type": "read-only",
"matcher": {
"id": "refs/tags/**",
"displayId": "refs/tags/**",
"type": {
"id": "PATTERN",
"name": "Pattern"
},
"active": true
},
"users": [
"bman",
"tstark",
"hulk"
],
"groups": [
"bitbucket-users"
],
"accessKeys": [
1,
2,
3
]
},
{
"type": "read-only",
"matcher": {
"id": "refs/heads/**",
"displayId": "refs/heads/**",
"type": {
"id": "PATTERN",
"name": "Pattern"
},
"active": true
},
"users": [
"bman",
"tstark",
"hulk"
],
"groups": [
"bitbucket-developers"
],
"accessKeys": []
}
]
Example response representations:
200 - application/json (restriction)
[
expand]
Example
[
{
"id": 2,
"scope": {
"resourceId": 2,
"type": "REPOSITORY"
},
"type": "READ_ONLY",
"matcher": null,
"users": [
{
"name": "jcitizen",
"emailAddress": "jane@example.com",
"id": 101,
"displayName": "Jane Citizen",
"active": true,
"slug": "jcitizen",
"type": "NORMAL"
}
],
"groups": [
"bitbucket-users"
],
"accessKeys": [
{
"key": {
"id": 1,
"text": "ssh-rsa AAAAAA... me@atlassian.com",
"label": "me@atlassian.com"
}
}
]
}
]
Response contains the ref restrictions that were just created.
Example
{
"errors": [
{
"context": "field_a",
"message": "A detailed validation error message for field_a.",
"exceptionName": null
},
{
"context": null,
"message": "A detailed error message.",
"exceptionName": null
}
]
}
The request has failed validation.
401 - application/json (validation)
[
expand]
Example
{
"errors": [
{
"context": null,
"message": "A detailed error message.",
"exceptionName": null
}
]
}
The currently authenticated user has insufficient permissions to perform this operation.
POST
Create a restriction for the supplied branch or set of branches to be applied on all repositories in the given project.
A restriction means preventing writes on the specified branch(es) by all except a set of users and/or groups, or preventing specific
operations such as branch deletion.
For example, you can restrict write access on 'master' to just the 'senior-developer' group, or prevent anyone from deleting that branch.
The request matcher and type must conform to the following.
- The matcher can be one of the following types
-
'BRANCH' represents a specific Branch name. You must supply the fully qualified name of the ref to restrict, e.g. "refs/heads/master"
instead of "master".
-
'PATTERN' represents a wildcard pattern that may match multiple branches. You must specify a valid
Branch Permission Pattern.
-
'MODEL_CATEGORY' represents Branch prefixes in the Branching model for the project. The 'id' must be one of
- 'FEATURE'
- 'BUGFIX'
- 'HOTFIX'
- 'RELEASE'
See the Branch REST API for more information.
-
'MODEL_BRANCH' represents either the Development or Production branch in the branching model for the project. The 'id' must be one of
- 'development'
- 'production'
See the Branch REST API for more information.
- Type: Set and be one of
- 'pull-request-only'
- 'fast-forward-only'
- 'no-deletes'
- 'read-only'
The authenticated user must have PROJECT_ADMIN permission or higher
to call this resource.
Only authenticated users may call this resource.
Example request representations:
Example
{
"type": "read-only",
"matcher": {
"id": "refs/tags/**",
"displayId": "refs/tags/**",
"type": {
"id": "PATTERN",
"name": "Pattern"
},
"active": true
},
"users": [
"bman",
"tstark",
"hulk"
],
"groups": [
"bitbucket-users"
],
"accessKeys": [
1,
2,
3
]
}
Example response representations:
200 - application/json (restriction)
[
expand]
Example
{
"id": 2,
"scope": {
"resourceId": 2,
"type": "REPOSITORY"
},
"type": "READ_ONLY",
"matcher": null,
"users": [
{
"name": "jcitizen",
"emailAddress": "jane@example.com",
"id": 101,
"displayName": "Jane Citizen",
"active": true,
"slug": "jcitizen",
"type": "NORMAL"
}
],
"groups": [
"bitbucket-users"
],
"accessKeys": [
{
"key": {
"id": 1,
"text": "ssh-rsa AAAAAA... me@atlassian.com",
"label": "me@atlassian.com"
}
}
]
}
Response contains the ref restriction that was just created.
Example
{
"errors": [
{
"context": "field_a",
"message": "A detailed validation error message for field_a.",
"exceptionName": null
},
{
"context": null,
"message": "A detailed error message.",
"exceptionName": null
}
]
}
The request has failed validation.
401 - application/json (validation)
[
expand]
Example
{
"errors": [
{
"context": null,
"message": "A detailed error message.",
"exceptionName": null
}
]
}
The currently authenticated user has insufficient permissions to perform this operation.
/rest/branch-permissions/2.0/projects/{projectKey}/restrictions/{id}
resource-wide template parameters
| parameter | value | description |
|---|
id | int | |
Methods
DELETE
Deletes a restriction as specified by a restriction id.
The authenticated user must have PROJECT_ADMIN permission or higher
to call this resource.
Only authenticated users may call this resource.
Example response representations:
an empty response indicating that the restriction no longer exists on the project
GET
Returns a restriction as specified by a restriction id.
The authenticated user must have REPO_ADMIN permission or higher
to call this resource.
Only authenticated users may call this resource.
Example response representations:
200 - application/json (restriction)
[
expand]
Example
{
"id": 2,
"scope": {
"resourceId": 2,
"type": "REPOSITORY"
},
"type": "READ_ONLY",
"matcher": null,
"users": [
{
"name": "jcitizen",
"emailAddress": "jane@example.com",
"id": 101,
"displayName": "Jane Citizen",
"active": true,
"slug": "jcitizen",
"type": "NORMAL"
}
],
"groups": [
"bitbucket-users"
],
"accessKeys": [
{
"key": {
"id": 1,
"text": "ssh-rsa AAAAAA... me@atlassian.com",
"label": "me@atlassian.com"
}
}
]
}
The restriction that was created
The restriction could not be found.