REST Resources Provided By: Bitbucket Server - REST

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

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 REST resources

Resources

Rest resource for retrieving, creating and deleting users or groups

/rest/api/1.0/admin/users

Methods

GET

/rest/api/1.0/admin/users?filter

This is a paged API.

Retrieve a page of users.

The authenticated user must have the LICENSED_USER permission to call this resource.

request query parameters
parametervaluedescription

filter

string

if specified only users with usernames, display name or email addresses containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL","directoryName":"Bitbucket Internal Directory","deletable":true,"lastAuthenticationTimestamp":1368145580548,"mutableDetails":true,"mutableGroups":true}],"start":0}

    A page of users.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not a licensed user.

DELETE

/rest/api/1.0/admin/users?name

Deletes the specified user, removing them from the system. This also removes any permissions that may have been granted to the user.

A user may not delete themselves, and a user with ADMIN permissions may not delete a user with SYS_ADMINpermissions.

The authenticated user must have the ADMIN permission to call this resource.

request query parameters
parametervaluedescription

name

string

the username identifying the user to delete

Example response representations:

  • 200 - application/json (detailedUser) [expand]

    Example
    {"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL","directoryName":"Bitbucket Internal Directory","deletable":true,"lastAuthenticationTimestamp":1368145580548,"mutableDetails":true,"mutableGroups":true}

    The deleted user.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as the authenticated user has a lower permission level than the user being deleted.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as a user can not delete themselves.

PUT

Update a user's details.

The authenticated user must have the ADMIN permission to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"name":"jcitizen","displayName":"Jane Citizen","email":"jane@example.com"}

Example response representations:

  • 200 - application/json (detailedUser) [expand]

    Example
    {"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL","directoryName":"Bitbucket Internal Directory","deletable":true,"lastAuthenticationTimestamp":1368145580548,"mutableDetails":true,"mutableGroups":true}

    The updated user.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission or has a lower permission level than the user being updated.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user does not exist.

POST

/rest/api/1.0/admin/users?name&password&displayName&emailAddress&addToDefaultGroup&notify

Creates a new user from the assembled query parameters.

The default group can be used to control initial permissions for new users, such as granting users the ability to login or providing read access to certain projects or repositories. If the user is not added to the default group, they may not be able to login after their account is created until explicit permissions are configured.

The authenticated user must have the ADMIN permission to call this resource.

request query parameters
parametervaluedescription

name

string

the username for the new user

password

string

the password for the new user

displayName

string

the display name for the new user

emailAddress

string

the e-mail address for the new user

addToDefaultGroup

boolean

Default: true

true to add the user to the default group, which can be used to grant them a set of initial permissions; otherwise, false to not add them to a group

notify

string

if present and not false instead of requiring a password, the create user will be notified via email their account has been created and requires a password to be reset. This option can only be used if a mail server has been configured

Example response representations:

  • 204 [expand]

    The user was successfully created.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user is not an administrator.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Adding the user to the default group would exceed the server's license limit.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Another user with the same name already exists.

/rest/api/1.0/admin/users/erasure

Methods

POST

/rest/api/1.0/admin/users/erasure?name

Erases personally identifying user data for a deleted user.

References in the application to the original username will be either removed or updated to a new non-identifying username. Refer to the support guide for details about what data is and isn't erased.

User erasure can only be performed on a deleted user. If the user has not been deleted first then this endpoint will return a bad request and no erasure will be performed.

Erasing user data is irreversible and may lead to a degraded user experience. This method should not be used as part of a standard user deletion and cleanup process.

Plugins can participate in user erasure by defining a <user-erasure-handler> module. If one or more plugin modules fail, an error summary of the failing modules is returned.

The authenticated user must have the ADMIN permission to call this resource.

request query parameters
parametervaluedescription

name

string

the username identifying the user to erase

Example response representations:

  • 200 - application/json (detailedUser) [expand]

    Example
    {"newIdentifier":"user-123ab"}

    The identifier of the erased user.

  • 400 - application/json (errors) [expand]

    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 was malformed (e.g. if no username was supplied).

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission or has a lower permission level than the user being erased.

  • 404 - application/json (errors) [expand]

    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 requested username does not exist.

  • 409 - application/json (errors) [expand]

    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 requested username is the username of a not deleted user.

GET

/rest/api/1.0/admin/users/erasure?name

Validate if a user can be erased.

A username is only valid for erasure if it exists as the username of a deleted user. This endpoint will return an appropriate error response if the supplied username is invalid for erasure.

This endpoint does not perform the actual user erasure, and will not modify the application in any way.

The authenticated user must have the ADMIN permission to call this resource.

request query parameters
parametervaluedescription

name

string

the username of the user to validate erasability for.

Example response representations:

  • 204 - application/json [expand]

    the user is erasable

  • 400 - application/json (errors) [expand]

    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 was malformed (e.g. if no username was supplied).

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission or has a lower permission level than the user being erased.

  • 404 - application/json (errors) [expand]

    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 requested username does not exist.

  • 409 - application/json (errors) [expand]

    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 requested username is the username of a not deleted user.

/rest/api/1.0/admin/users/rename

Methods

POST

Rename a user.

The authenticated user must have the ADMIN permission to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"name":"jcitizen","newName":"jcitizen-new"}

Example response representations:

  • 200 - application/json (detailedUser) [expand]

    Example
    {"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL","directoryName":"Bitbucket Internal Directory","deletable":true,"lastAuthenticationTimestamp":1368145580548,"mutableDetails":true,"mutableGroups":true}

    The renamed user.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission or has a lower permission level than the user being renamed.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user does not exist.

/rest/api/1.0/admin/users/credentials

Methods

PUT

Update a user's password.

The authenticated user must have the ADMIN permission to call this resource, and may not update the password of a user with greater permissions than themselves.

Example request representations:

  • application/json [expand]

    Example
    {"password":"secret","passwordConfirm":"secret","name":"jcitizen"}

Example response representations:

  • 204 [expand]

    The user's password was successfully updated.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission or has a lower permission level than the user having their password updated.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user does not exist.

/rest/api/1.0/admin/users/captcha

Methods

DELETE

/rest/api/1.0/admin/users/captcha?name

Clears any CAPTCHA challenge that may constrain the user with the supplied username when they authenticate. Additionally any counter or metric that contributed towards the user being issued the CAPTCHA challenge (for instance too many consecutive failed logins) will also be reset.

The authenticated user must have the ADMIN permission to call this resource, and may not clear the CAPTCHA of a user with greater permissions than themselves.

request query parameters
parametervaluedescription

name

string

the username

Example response representations:

  • 204 - application/json [expand]

    The CAPTCHA was successfully cleared.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as the authenticated user has a lower permission level than the user to clear captcha for.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user does not exist.

/rest/api/1.0/admin/groups

Methods

DELETE

/rest/api/1.0/admin/groups?name

Deletes the specified group, removing them from the system. This also removes any permissions that may have been granted to the group.

A user may not delete the last group that is granting them administrative permissions, or a group with greater permissions than themselves.

The authenticated user must have the ADMIN permission to call this resource.

request query parameters
parametervaluedescription

name

string

the name identifying the group to delete

Example response representations:

  • 200 - application/json (detailedGroup) [expand]

    Example
    {"name":"group-a","deletable":true}

    The deleted group.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as the authenticated user has a lower permission level than the group being deleted.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified group does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would lower the authenticated user's permission level.

POST

/rest/api/1.0/admin/groups?name

Create a new group.

The authenticated user must have ADMIN permission or higher to call this resource.

request query parameters
parametervaluedescription

name

string

Name of the group.

Example response representations:

  • 200 - application/json (restDetailedGroup) [expand]

    Example
    {"name":"group-a","deletable":true}

    The newly created group.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    A group with this name already exists.

GET

/rest/api/1.0/admin/groups?filter

This is a paged API.

Retrieve a page of groups.

The authenticated user must have LICENSED_USER permission or higher to call this resource.

request query parameters
parametervaluedescription

filter

string

if specified only group names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"group-a","deletable":true}],"start":0}

    A page of groups.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not a licensed user.

/rest/api/1.0/admin/groups/add-user

Methods

POST

Deprecated since 2.10. Use /rest/users/add-groups instead.

Add a user to a group.

In the request entity, the context attribute is the group and the itemName is the user.

The authenticated user must have the ADMIN permission to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"context":"group_a","itemName":"user_a"}

Example response representations:

  • 200 [expand]

    The user was added to the group

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would exceed the server's licensing limit, or the groups permissions exceed the authenticated user's permission level.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user or group does not exist.

/rest/api/1.0/admin/users/add-group

Methods

POST

Deprecated since 2.10. Use /rest/users/add-groups instead.

Add a user to a group. This is very similar to groups/add-user, but with the context and itemName attributes of the supplied request entity reversed. On the face of it this may appear redundant, but it facilitates a specific UI component in Stash.

In the request entity, the context attribute is the user and the itemName is the group.

The authenticated user must have the ADMIN permission to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"context":"user_a","itemName":"group_a"}

Example response representations:

  • 200 [expand]

    The user was added to the group

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would exceed the server's licensing limit, or the groups permissions exceed the authenticated user's permission level.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user or group does not exist.

/rest/api/1.0/admin/groups/add-users

Methods

POST

Add multiple users to a group.

The authenticated user must have the ADMIN permission to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"group":"group","users":["user1","user2"]}

Example response representations:

  • 200 [expand]

    All the users were added to the group

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would exceed the server's licensing limit, or the group's permissions exceed the authenticated user's permission level.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified group or users do not exist.

/rest/api/1.0/admin/users/add-groups

Methods

POST

Add a user to one or more groups.

The authenticated user must have the ADMIN permission to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"user":"user","groups":["group_a","group_b"]}

Example response representations:

  • 200 [expand]

    The user was added to all the groups

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would exceed the server's licensing limit, or the groups permissions exceed the authenticated user's permission level.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user or groups do not exist.

/rest/api/1.0/admin/groups/remove-user

Methods

POST

Deprecated since 2.10. Use /rest/users/remove-groups instead.

Remove a user from a group.

The authenticated user must have the ADMIN permission to call this resource.

In the request entity, the context attribute is the group and the itemName is the user.

Example request representations:

  • application/json [expand]

    Example
    {"context":"group_a","itemName":"user_a"}

Example response representations:

  • 200 [expand]

    The user was removed from the group.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as the group has a higher permission level than the context user.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user or group does not exist.

/rest/api/1.0/admin/users/remove-group

Methods

POST

Remove a user from a group. This is very similar to groups/remove-user, but with the context and itemName attributes of the supplied request entity reversed. On the face of it this may appear redundant, but it facilitates a specific UI component in Stash.

In the request entity, the context attribute is the user and the itemName is the group.

The authenticated user must have the ADMIN permission to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"context":"user_a","itemName":"group_a"}

Example response representations:

  • 200 [expand]

    The user was removed from the group.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have the ADMIN permission.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as the group has a higher permission level than the context user.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user or group does not exist.

/rest/api/1.0/admin/groups/more-members

Methods

GET

/rest/api/1.0/admin/groups/more-members?context&filter

This is a paged API.

Retrieves a list of users that are members of a specified group.

The authenticated user must have the LICENSED_USER permission to call this resource.

request query parameters
parametervaluedescription

context

string

the group which should be used to locate members

filter

string

Default:

if specified only users with usernames, display names or email addresses containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL","directoryName":"Bitbucket Internal Directory","deletable":true,"lastAuthenticationTimestamp":1368145580548,"mutableDetails":true,"mutableGroups":true}],"start":0}

    A page of users.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not a licensed user.

/rest/api/1.0/admin/groups/more-non-members

Methods

GET

/rest/api/1.0/admin/groups/more-non-members?context&filter

This is a paged API.

Retrieves a list of users that are not members of a specified group.

The authenticated user must have the LICENSED_USER permission to call this resource.

request query parameters
parametervaluedescription

context

string

the group which should be used to locate non-members

filter

string

Default:

if specified only users with usernames, display names or email addresses containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL","directoryName":"Bitbucket Internal Directory","deletable":true,"lastAuthenticationTimestamp":1368145580548,"mutableDetails":true,"mutableGroups":true}],"start":0}

    A page of users.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not a licensed user.

/rest/api/1.0/admin/users/more-members

Methods

GET

/rest/api/1.0/admin/users/more-members?context&filter

This is a paged API.

Retrieves a list of groups the specified user is a member of.

The authenticated user must have the LICENSED_USER permission to call this resource.

request query parameters
parametervaluedescription

context

string

the user which should be used to locate groups

filter

string

Default:

if specified only groups with names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"group-a","deletable":true}],"start":0}

    A page of groups.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not a licensed user.

/rest/api/1.0/admin/users/more-non-members

Methods

GET

/rest/api/1.0/admin/users/more-non-members?context&filter

This is a paged API.

Retrieves a list of groups the specified user is not a member of.

The authenticated user must have the LICENSED_USER permission to call this resource.

request query parameters
parametervaluedescription

context

string

the user which should be used to locate groups

filter

string

Default:

if specified only groups with names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"group-a","deletable":true}],"start":0}

    A page of groups.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not a licensed user.

/rest/api/1.0/admin/banner

Methods

GET

Gets the announcement banner, if one exists and is available to the user

Example response representations:

  • 200 - application/json (banner) [expand]

    Example
    {"audience":"ALL","enabled":true,"message":"- Example *Markdown*\nMessage"}

    The requested banner

  • 204 [expand]

    There is no banner to display

  • 401 [expand]

    The user does not have permission to access the banner service through this endpoint

DELETE

Deletes a banner, if one is present in the database.

Example response representations:

  • 204 [expand]

    The query executed successfully, whether a banner was deleted or not

  • 401 [expand]

    The user does not have permission to access the banner service through this endpoint

PUT

Sets the announcement banner with the provided JSON. Only users authenticated as Admins may call this resource

Example request representations:

Example response representations:

  • 204 [expand]

    The banner was set successfully

  • 400 [expand]

    There was malformed or incorrect data in the provided JSON

  • 401 [expand]

    The user does not have permission to access the banner service through this endpoint

/rest/api/1.0/admin/cluster

Methods

GET

Gets information about the nodes that currently make up the stash cluster.

The authenticated user must have the SYS_ADMIN permission to call this resource.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"localNode":{"id":"d4fde8b1-2504-4998-a0ba-14fbe98edd4d","buildVersion":"7.0.0","name":"foo","address":{"hostName":"foo","port":5000},"local":true},"nodes":[{"id":"73518909-8e86-445b-8345-fcbf2e0934b6","buildVersion":"7.0.0","name":"bar","address":{"hostName":"bar","port":5001},"local":true},{"id":"d4fde8b1-2504-4998-a0ba-14fbe98edd4d","buildVersion":"7.0.0","name":"foo","address":{"hostName":"foo","port":5000},"local":true}],"running":true}

    Information about the cluster

  • 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 cluster information.

/rest/api/1.0/admin/default-branch

Methods

GET

Retrieves the configured global default branch, which is used when creating new repositories if an explicit default branch is not specified.

The user must be authenticated to call this resource.

Example response representations:

  • 200 - application/json (defaultBranch) [expand]

    Example
    {"id":"main"}

    The configured global default branch.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    No global default branch has been configured.

PUT

Configures the global default branch, which is used when creating new repositories if an explicit default branch is not specified.

The authenticated user must have ADMIN permission to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"id":"main"}

Example response representations:

  • 204 [expand]

    The default branch has been set.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The current user does not have sufficient permissions to configure the global default branch.

DELETE

Clears the global default branch, which is used when creating new repositories if an explicit default branch is not specified, if one has been configured.

The authenticated user must have ADMIN permission to call this resource.

Example response representations:

  • 204 [expand]

    The default branch has been cleared.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The current user does not have sufficient permissions to clear the global default branch.

/rest/api/1.0/admin/license

A REST endpoint for retrieving or updating the license.

Methods

GET

Retrieves details about the current license, as well as the current status of the system with regards to the installed license. The status includes the current number of users applied toward the license limit, as well as any status messages about the license (warnings about expiry or user counts exceeding license limits).

The authenticated user must have ADMIN permission. Unauthenticated users, and non-administrators, are not permitted to access license details.

Example response representations:

  • 200 - application/json (license) [expand]

    Example
    {"creationDate":1331038800000,"purchaseDate":1331038800000,"expiryDate":1372493732817,"numberOfDaysBeforeExpiry":0,"maintenanceExpiryDate":1372493732817,"numberOfDaysBeforeMaintenanceExpiry":0,"gracePeriodEndDate":1372493732817,"numberOfDaysBeforeGracePeriodExpiry":0,"maximumNumberOfUsers":12,"unlimitedNumberOfUsers":false,"serverId":"<server ID embedded in license>","supportEntitlementNumber":"<support entitlement number embedded in license>","license":"<encoded license text>","status":{"serverId":"<actual server ID>","currentNumberOfUsers":2}}

    The currently-installed license.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the license, or the request is anonymous.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    No license has been installed.

POST

Decodes the provided encoded license and sets it as the active license. If no license was provided, a 400 is returned. If the license cannot be decoded, or cannot be applied, a 409 is returned. Some possible reasons a license may not be applied include:

  • It is for a different product
  • It is already expired
Otherwise, if the license is updated successfully, details for the new license are returned with a 200 response.

Warning: It is possible to downgrade the license during update, applying a license with a lower number of permitted users. If the number of currently-licensed users exceeds the limits of the new license, pushing will be disabled until the licensed user count is brought into compliance with the new license.

The authenticated user must have SYS_ADMIN permission. ADMIN users may view the current license details, but they may not update the license.

Example request representations:

  • application/json [expand]

    Example
    {"license":"<encoded license text>"}

Example response representations:

  • 200 - application/json (license) [expand]

    Example
    {"creationDate":1331038800000,"purchaseDate":1331038800000,"expiryDate":1372493732817,"numberOfDaysBeforeExpiry":0,"maintenanceExpiryDate":1372493732817,"numberOfDaysBeforeMaintenanceExpiry":0,"gracePeriodEndDate":1372493732817,"numberOfDaysBeforeGracePeriodExpiry":0,"maximumNumberOfUsers":12,"unlimitedNumberOfUsers":false,"serverId":"<server ID embedded in license>","supportEntitlementNumber":"<support entitlement number embedded in license>","license":"<encoded license text>","status":{"serverId":"<actual server ID>","currentNumberOfUsers":2}}

    The newly-installed license.

  • 400 - application/json (errors) [expand]

    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}]}

    No encoded license was provided in the JSON body for the POST.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update the license.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The encoded license could not be decoded, or it is not valid for use on this server. For example, it may be for a different product, or it may have already expired.

/rest/api/1.0/admin/mail-server

Methods

PUT

Updates the mail configuration The authenticated user must have the SYS_ADMIN permission to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"hostname":"smtp.example.com","port":465,"protocol":"SMTP","use-start-tls":true,"require-start-tls":false,"username":"user","sender-address":"stash-no-reply@company.com"}

Example response representations:

  • 200 - application/json (mailConfiguration) [expand]

    Example
    {"hostname":"smtp.example.com","port":465,"protocol":"SMTP","use-start-tls":true,"require-start-tls":false,"username":"user","sender-address":"stash-no-reply@company.com"}

    The updated mail configuration.

  • 400 - application/json (errors) [expand]

    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 mail configuration was not updated due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update the mail configuration.

GET

Retrieves the current mail configuration. The authenticated user must have the SYS_ADMIN permission to call this resource.

Example response representations:

  • 200 - application/json (mailHostConfiguration) [expand]

    Example
    {"hostname":"smtp.example.com","port":465,"protocol":"SMTP","use-start-tls":true,"require-start-tls":false,"username":"user","sender-address":"stash-no-reply@company.com"}

    The mail configuration.

  • 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 mail configuration.

  • 404 - application/json [expand]

    The mail server hasn't been configured

DELETE

Deletes the current mail configuration.

The authenticated user must have the SYS_ADMIN permission to call this resource.

Example response representations:

  • 204 - application/json [expand]

    The mail configuration was successfully 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 mail server configuration.

/rest/api/1.0/admin/mail-server/sender-address

Methods

GET

Retrieves the server email address

Example response representations:

  • 200 - application/json (server email address) [expand]

    Example
    "stash-no-reply@company.com"

    The server email address

  • 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 server email address.

  • 404 - application/json [expand]

    The server email address is not set

DELETE

Clears the server email address.

The authenticated user must have the ADMIN permission to call this resource.

Example response representations:

  • 204 - application/json [expand]

    The server email address was successfully cleared.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to clear the server email address.

PUT

Updates the server email address The authenticated user must have the ADMIN permission to call this resource.

Example request representations:

  • application/json [expand]

    Example
    "stash-no-reply@company.com"

Example response representations:

  • 200 - application/json (senderAddress) [expand]

    Example
    "stash-no-reply@company.com"

    The updated server email address.

  • 400 - application/json (errors) [expand]

    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 server email address was not updated due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update the server email address.

/rest/api/1.0/admin/permissions/groups

Methods

GET

/rest/api/1.0/admin/permissions/groups?filter

This is a paged API.

Retrieve a page of groups that have been granted at least one global permission.

The authenticated user must have ADMIN permission or higher to call this resource.

request query parameters
parametervaluedescription

filter

string

Default:

if specified only group names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"group":{"name":"group_a"},"permission":"ADMIN"}],"start":0}

    A page of groups and their highest global permissions.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator.

PUT

/rest/api/1.0/admin/permissions/groups?permission&name

Promote or demote a user's global permission level. Available global permissions are:

  • LICENSED_USER
  • PROJECT_CREATE
  • ADMIN
  • SYS_ADMIN
See the Bitbucket Server documentation for a detailed explanation of what each permission entails.

The authenticated user must have:

  • ADMIN permission or higher; and
  • the permission they are attempting to grant or higher; and
  • greater or equal permissions than the current permission level of the group (a user may not demote the permission level of a group with higher permissions than them)
to call this resource. In addition, a user may not demote a group's permission level if their own permission level would be reduced as a result.

request query parameters
parametervaluedescription

permission

string

the permission to grant

name

string

the names of the groups

Example response representations:

  • 204 [expand]

    The specified permission was granted to the specified user.

  • 400 - application/json (errors) [expand]

    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 was malformed or the specified permission does not exist.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator or doesn't have the specified permission they are attempting to grant.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would exceed the server's license limits.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified group does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would reduce the currently authenticated user's permission level or the currently authenticated user has a lower permission level than the group they are attempting to modify.

DELETE

/rest/api/1.0/admin/permissions/groups?name

Revoke all global permissions for a group.

The authenticated user must have:

  • ADMIN permission or higher; and
  • greater or equal permissions than the current permission level of the group (a user may not demote the permission level of a group with higher permissions than them)
to call this resource. In addition, a user may not revoke a group's permissions if their own permission level would be reduced as a result.

request query parameters
parametervaluedescription

name

string

the name of the group

Example response representations:

  • 204 [expand]

    All global permissions were revoked from the group.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified group does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would reduce the currently authenticated user's permission level or the currently authenticated user has a lower permission level than the group they are attempting to modify.

/rest/api/1.0/admin/permissions/groups/none

Methods

GET

/rest/api/1.0/admin/permissions/groups/none?filter

This is a paged API.

Retrieve a page of groups that have no granted global permissions.

The authenticated user must have ADMIN permission or higher to call this resource.

request query parameters
parametervaluedescription

filter

string

Default:

if specified only group names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"group-a","deletable":true}],"start":0}

    A page of groups that have not been granted any global permissions.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator.

/rest/api/1.0/admin/permissions/users

Methods

GET

/rest/api/1.0/admin/permissions/users?filter

This is a paged API.

Retrieve a page of users that have been granted at least one global permission.

The authenticated user must have ADMIN permission or higher to call this resource.

request query parameters
parametervaluedescription

filter

string

Default:

if specified only user names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"permission":"ADMIN"}],"start":0}

    A page of users and their highest global permissions.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator.

PUT

/rest/api/1.0/admin/permissions/users?name&permission

Promote or demote the global permission level of a user. Available global permissions are:

  • LICENSED_USER
  • PROJECT_CREATE
  • ADMIN
  • SYS_ADMIN
See the Bitbucket Server documentation for a detailed explanation of what each permission entails.

The authenticated user must have:

  • ADMIN permission or higher; and
  • the permission they are attempting to grant; and
  • greater or equal permissions than the current permission level of the user (a user may not demote the permission level of a user with higher permissions than them)
to call this resource. In addition, a user may not demote their own permission level.

request query parameters
parametervaluedescription

name

string

the names of the users

permission

string

the permission to grant

Example response representations:

  • 204 [expand]

    The requested permission was granted.

  • 400 - application/json (errors) [expand]

    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 was malformed or the specified permission does not exist.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator or doesn't have the specified permission they are attempting to grant.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would exceed the server's license limits.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would reduce the currently authenticated user's permission level or the currently authenticated user has a lower permission level than the user they are attempting to modify.

DELETE

/rest/api/1.0/admin/permissions/users?name

Revoke all global permissions for a user.

The authenticated user must have:

  • ADMIN permission or higher; and
  • greater or equal permissions than the current permission level of the user (a user may not demote the permission level of a user with higher permissions than them)
to call this resource. In addition, a user may not demote their own permission level.

request query parameters
parametervaluedescription

name

string

the name of the user

Example response representations:

  • 204 [expand]

    All global permissions were revoked from the user.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would reduce the currently authenticated user's permission level or the currently authenticated user has a lower permission level than the user they are attempting to modify.

/rest/api/1.0/admin/permissions/users/none

Methods

GET

/rest/api/1.0/admin/permissions/users/none?filter

This is a paged API.

Retrieve a page of users that have no granted global permissions.

The authenticated user must have ADMIN permission or higher to call this resource.

request query parameters
parametervaluedescription

filter

string

Default:

if specified only user names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}],"start":0}

    A page of users that have not been granted any global permissions.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator.

/rest/api/1.0/admin/pull-requests/{scmId}

resource-wide template parameters
parametervaluedescription

scmId

string

the id of the scm to get strategies for

Methods

GET

This is a paged API.

Retrieve the merge strategies available for this instance.

The user must be authenticated to call this resource.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"commitSummaries":20,"defaultStrategy":{"description":"Always create a merge commit","enabled":true,"flag":"--no-ff","id":"no-ff","name":"Merge commit"},"strategies":[{"description":"Always create a merge commit","enabled":true,"flag":"--no-ff","id":"no-ff","name":"Merge commit"}],"type":"repository"}

    The merge configuration of this instance.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to see the request repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The request repository does not exist.

POST

Update the pull request merge strategies for the context repository.

The authenticated user must have ADMIN permission to call this resource.

Only the strategies provided will be enabled, only one may be set to default

An explicitly set pull request merge strategy configuration can be deleted by POSTing a document with an empty "mergeConfig" attribute. i.e:

 {
     "mergeConfig": {
     }
 }
 
Upon completion of this request, the effective configuration will be the default configuration.

Example request representations:

  • application/json [expand]

    Example
    {"commitSummaries":20,"defaultStrategy":{"id":"no-ff"},"strategies":[{"id":"no-ff"}]}

Example response representations:

  • 200 - application/json (strategies) [expand]

    Example
    {"commitSummaries":20,"defaultStrategy":{"description":"Always create a merge commit","enabled":true,"flag":"--no-ff","id":"no-ff","name":"Merge commit"},"strategies":[{"description":"Always create a merge commit","enabled":true,"flag":"--no-ff","id":"no-ff","name":"Merge commit"}],"type":"repository"}

    The repository pull request merge strategies for the context repository.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository pull request merge strategies were not updated due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to administrate the specified repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

/rest/api/1.0/admin/rate-limit/history

Methods

GET

/rest/api/1.0/admin/rate-limit/history?order

Retrieves the recent rate limit history for the instance.

The authenticated user must have the ADMIN permission to call this resource.

request query parameters
parametervaluedescription

order

string

an optional sort category to arrange the results in descending order by either {@link AggregateRejectCounterOrder#NEWEST} or {@link AggregateRejectCounterOrder#FREQUENCY}

Example response representations:

  • 200 - application/json [expand]

    A response containing a page of aggregated counters for users who have been recently rate limited.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The sort query parameter is invalid.

  • 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 rate limit history.

/rest/api/1.0/admin/rate-limit/settings

Methods

PUT

Sets the rate limit settings for the instance.

The authenticated user must have ADMIN permission to call this resource.

Example request representations:

Example response representations:

  • 200 - application/json [expand]

    Example
    {"enabled":true,"defaultSettings":{"capacity":60,"fillRate":5}}

    A response containing the updated rate limit plugin settings for the instance.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    One of the following error cases occurred (check the error message for more details):

    • The request is empty
    • The enabled field of the request is not a boolean
    • The defaultSettings field of the request does not contain both capacity and fillRate
    • The capacity and fillRate are not positive integers

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to set rate limit settings.

GET

Retrieves the rate limit settings for the instance.

The user must be authenticated to call this resource.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"enabled":true,"defaultSettings":{"capacity":60,"fillRate":5}}

    A response containing the rate limit plugin settings for the instance.

  • 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 rate limit settings.

/rest/api/1.0/admin/rate-limit/settings/users

Methods

GET

/rest/api/1.0/admin/rate-limit/settings/users?filter

Retrieves the user-specific rate limit settings for the given user.

The authenticated user must have ADMIN permission to call this resource.

request query parameters
parametervaluedescription

filter

string

Example response representations:

  • 200 - application/json [expand]

    Example
    {"size":2,"limit":25,"isLastPage":true,"values":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"settings":{"capacity":60,"fillRate":5}},{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"whitelisted":true}],"start":0}

    A response containing all the user-specific rate limit settings filtered by the optional filter.

  • 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 rate limit settings.

POST

Sets the given rate limit settings for the given user.

The authenticated user must have ADMIN permission to call this resource.

Example request representations:

Example response representations:

  • 200 - application/json [expand]

    Example
    {"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"settings":{"capacity":60,"fillRate":5}}

    A response containing the updated user settings

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    One of the following valid state error cases occurred (check the error message for more details):

    • The request is empty
    • Whitelisted is false or not provided, and no settings are provided either
    • Whitelisted is false or not provided, settings are provided, but do not contain both capacity and fillRate
    • Whitelisted is false or not provided, settings are provided, but capacity and fillRate are not positive integers
    • Whitelisted is true, and settings are provided (only one must be provided)

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to set user settings.

/rest/api/1.0/admin/rate-limit/settings/users/{userSlug}

Methods

GET

Retrieves the user-specific rate limit settings for the given user.

To call this resource, the user must be authenticated and either have ADMIN permission or be the same user as the one whose settings are requested. A user with ADMIN permission cannot get the settings of a user with SYS_ADMIN permission.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"settings":{"capacity":60,"fillRate":5}}

    A response containing the user-specific rate limit settings for the given user.

  • 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 rate limit settings.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user does not exist, or has no settings

DELETE

Deletes the user-specific rate limit settings for the given user.

The authenticated user must have ADMIN permission to call this resource.

Example response representations:

  • 204 - application/json [expand]

    an empty response indicating that the user settings have been 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 retrieve rate limit settings.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user does not exist, or has no settings

PUT

Sets the given rate limit settings for the given user.

The authenticated user must have ADMIN permission to call this resource.

Example request representations:

Example response representations:

  • 200 - application/json [expand]

    Example
    {"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"settings":{"capacity":60,"fillRate":5}}

    A response containing the updated user settings

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    One of the following valid state error cases occurred (check the error message for more details):

    • The request is empty
    • Whitelisted is false or not provided, and no settings are provided either
    • Whitelisted is false or not provided, settings are provided, but do not contain both capacity and fillRate
    • Whitelisted is false or not provided, settings are provided, but capacity and fillRate are not positive integers
    • Whitelisted is true, and settings are provided (only one must be provided)

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to set user settings.

/rest/api/1.0/application-properties

Methods

GET

Retrieve version information and other application properties.

No authentication is required to call this resource.

Example response representations:

  • 200 - application/json (applicationProperties) [expand]

    Example
    {"version":"2.1.0","buildNumber":"20130123103656677","buildDate":"1358897885952000","displayName":"Example.com Bitbucket"}

    The application properties.

/rest/api/1.0/build/capabilities

Methods

GET

This is a paged API.

Returns the build capabilities of this instance

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {}

    capabilities

REST Resource for personal dashboards

/rest/api/1.0/dashboard/pull-request-suggestions

Methods

GET

/rest/api/1.0/dashboard/pull-request-suggestions?changesSince&limit

This is a paged API.

Retrieves a page of suggestions for pull requests that the currently authenticated user may wish to raise. Such suggestions are based on ref changes occurring and so contain the ref change that prompted the suggestion plus the time the change event occurred. Changes will be returned in descending order based on the time the change that prompted the suggestion occurred.

Note that although the response is a page object, the interface does not support paging, however a limit can be applied to the size of the returned page.

request query parameters
parametervaluedescription

changesSince

string

Default: 172800

restrict pull request suggestions to be based on events that occurred since some time in the past. This is expressed in seconds since "now". So to return suggestions based only on activity within the past 48 hours, pass a value of 172800.

limit

int

Default: 3

restricts the result set to return at most this many suggestions.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"changeTime":1359075920,"refChange":{"ref":{"id":"refs/heads/master","displayId":"master","type":"BRANCH"},"refId":"refs/heads/master","fromHash":"6053a1eaa1c009dd11092d09a72f3c41af1b59ad","toHash":"d6edcbf924697ab811a867421dab60d954ccad99","type":"UPDATE"},"repository":{"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}},"fromRef":{"id":"refs/heads/main","displayId":"main","type":"BRANCH"},"toRef":{"id":"refs/heads/main","displayId":"main","type":"BRANCH"}}],"start":0}

    A page of pull requests that match the search criteria.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The current user is not authenticated

/rest/api/1.0/dashboard/pull-requests

Methods

GET

/rest/api/1.0/dashboard/pull-requests?state&role&participantStatus&order&closedSince

This is a paged API.

Retrieve a page of pull requests where the current authenticated user is involved as either a reviewer, author or a participant. The request may be filtered by pull request state, role or participant status.

request query parameters
parametervaluedescription

state

string

(optional, defaults to returning pull requests in any state). If a state is supplied only pull requests in the specified state will be returned. Either OPEN, DECLINED or MERGED. Omit this parameter to return pull request in any state.

role

string

(optional, defaults to returning pull requests for any role). If a role is supplied only pull requests where the authenticated user is a participant in the given role will be returned. Either REVIEWER, AUTHOR or PARTICIPANT.

participantStatus

string

(optional, defaults to returning pull requests with any participant status). A comma separated list of participant status. That is, one or more of UNAPPROVED, NEEDS_WORK, or APPROVED.

order

string

(optional, defaults to NEWEST) the order to return pull requests in, either OLDEST (as in: "oldest first"), NEWEST, PARTICIPANT_STATUS, or CLOSED_DATE. Where CLOSED_DATE is specified and the result set includes pull requests that are not in the closed state, these pull requests will appear first in the result set, followed by most recently closed pull requests.

closedSince

string

(optional, defaults to returning pull requests regardless of closed since date). Permits returning only pull requests with a closed timestamp set more recently that (now - closedSince). Units are in seconds. So for example if closed since 86400 is set only pull requests closed in the previous 24 hours will be returned.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"id":101,"version":1,"title":"Talking Nerdy","description":"It’s a kludge, but put the tuple from the database in the cache.","state":"OPEN","open":true,"closed":false,"createdDate":1359075920,"updatedDate":1359085920,"fromRef":{"id":"refs/heads/feature-ABC-123","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"toRef":{"id":"refs/heads/master","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"locked":false,"author":{"user":{"name":"tom","emailAddress":"tom@example.com","id":115026,"displayName":"Tom","active":true,"slug":"tom","type":"NORMAL"},"role":"AUTHOR","approved":true,"status":"APPROVED"},"reviewers":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":true,"status":"APPROVED"}],"participants":[{"user":{"name":"harry","emailAddress":"harry@example.com","id":99049120,"displayName":"Harry","active":true,"slug":"harry","type":"NORMAL"},"role":"PARTICIPANT","approved":true,"status":"APPROVED"},{"user":{"name":"dick","emailAddress":"dick@example.com","id":3083181,"displayName":"Dick","active":true,"slug":"dick","type":"NORMAL"},"role":"PARTICIPANT","approved":false,"status":"UNAPPROVED"}],"links":{"self":[{"href":"http://link/to/pullrequest"}]}}],"start":0}

    A page of pull requests that match the search criteria.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The current user is not authenticated

/rest/api/1.0/deployment/capabilities

Methods

GET

This is a paged API.

Returns the Deployment capabilities of this instance

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {}

    capabilities

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    This instance of Bitbucket Server does not support deployments (for example, it has been disabled using the property 'plugin.deployment.capability.disabled').

/rest/api/1.0/groups

Methods

GET

/rest/api/1.0/groups?filter

This is a paged API.

Retrieve a page of group names.

The authenticated user must have LICENSED_USER permission or higher to call this resource.

request query parameters
parametervaluedescription

filter

string

if specified only group names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":2,"limit":25,"isLastPage":true,"values":["group_a","group_b"],"start":0}

    A page of group names.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not a project administrator.

/rest/api/1.0/hooks/{hookKey}/avatar

resource-wide template parameters
parametervaluedescription

hookKey

string

the complete module key of the hook module

Methods

GET

/rest/api/1.0/hooks/{hookKey}/avatar?version

Retrieve the avatar for the project matching the supplied moduleKey.

request query parameters
parametervaluedescription

version

string

optional version used for HTTP caching only - any non-blank version will result in a large max-age Cache-Control header. Note that this does not affect the Last-Modified header.

Example response representations:

  • 200 - image/png [expand]

    The avatar of the project matching the supplied projectKey.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the project.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project does not exist.

/rest/api/1.0/inbox/pull-requests/count

Methods

GET

Example response representations:

  • application/json; charset=UTF-8 [expand]

/rest/api/1.0/inbox/pull-requests

Methods

GET

/rest/api/1.0/inbox/pull-requests?start&limit&role
request query parameters
parametervaluedescription

start

int

Default: 0

limit

int

Default: 25

role

string

Default: reviewer

Example response representations:

  • application/json; charset=UTF-8 [expand]

/rest/api/1.0/labels

Methods

GET

/rest/api/1.0/labels?prefix

Returns a paged response of all the labels in the system.

The user needs to be authenticated to use this resource.

request query parameters
parametervaluedescription

prefix

string

(optional) prefix to filter the labels on.

Example response representations:

  • 201 - application/json (label) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"labelName"}],"start":0}

    Page of returned labels.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The user is currently not authenticated.

/rest/api/1.0/labels/{labelName}

resource-wide template parameters
parametervaluedescription

labelName

string

the label name

Methods

GET

Returns a label.

The user needs to be authenticated to use this resource.

Example response representations:

  • 200 - application/json (label) [expand]

    Example
    {"name":"labelName"}

    The label.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The user is currently not authenticated.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified label does not exist.

/rest/api/1.0/labels/{labelName}/labeled

resource-wide template parameters
parametervaluedescription

labelName

string

the label name, provided on the path

Methods

GET

/rest/api/1.0/labels/{labelName}/labeled?type

Returns a page of labelables for a given label.

Only labelables that the authenticated user has view access to will be returned.

request query parameters
parametervaluedescription

type

string

the type of labelables to be returned. Supported values: REPOSITORY

Example response representations:

  • 200 - application/json (labelables) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]},"labelableType":"REPOSITORY"}],"start":0}

    The page of labelables.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The type of labelable is incorrect, correct values are 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 labelables

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified label does not exist.

/rest/api/1.0/logs/rootLogger/{levelName}

resource-wide template parameters
parametervaluedescription

levelName

string

the level to set the logger to. Either TRACE, DEBUG, INFO, WARN or ERROR

Methods

PUT

Set the current log level for the root logger.

The authenticated user must have ADMIN permission or higher to call this resource.

Example response representations:

  • 204 - application/json [expand]

    The log level was successfully changed.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The log level was invalid.

  • 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 log level.

/rest/api/1.0/logs/rootLogger

Methods

GET

Retrieve the current log level for the root logger.

The authenticated user must have ADMIN permission or higher to call this resource.

Example response representations:

  • 200 - application/json (logLevel) [expand]

    Example
    {"logLevel":"DEBUG"}

    The log level of the logger.

  • 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 log level.

/rest/api/1.0/logs/logger/{loggerName}/{levelName}

resource-wide template parameters
parametervaluedescription

levelName

string

the level to set the logger to. Either TRACE, DEBUG, INFO, WARN or ERROR

loggerName

string

the name of the logger.

Methods

PUT

Set the current log level for a given logger.

The authenticated user must have ADMIN permission or higher to call this resource.

Example response representations:

  • 204 - application/json [expand]

    The log level was successfully changed.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The log level was invalid.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to set the log level.

/rest/api/1.0/logs/logger/{loggerName}

resource-wide template parameters
parametervaluedescription

loggerName

string

the name of the logger.

Methods

GET

Retrieve the current log level for a given logger.

The authenticated user must have ADMIN permission or higher to call this resource.

Example response representations:

  • 200 - application/json (logLevel) [expand]

    Example
    {"logLevel":"DEBUG"}

    The log level of the logger.

  • 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 log level.

/rest/api/1.0/markup/preview

Methods

POST

/rest/api/1.0/markup/preview?hardwrap&htmlEscape&includeHeadingId&urlMode

Preview generated HTML for the given markdown content.

Only authenticated users may call this resource.

request query parameters
parametervaluedescription

hardwrap

boolean

(Optional) Whether the markup implementation should convert newlines to breaks. By default this is false which reflects the standard markdown specification.

htmlEscape

boolean

(Optional) true if HTML should be escaped in the input markup, false otherwise.

includeHeadingId

boolean

(Optional) true if headers should contain an ID based on the heading content.

urlMode

string

(Optional) The mode to use when building URLs. One of: ABSOLUTE, RELATIVE or CONFIGURED. By default this is RELATIVE.

Example request representations:

  • */* [expand]

    Example
    # Hello World!

Example response representations:

  • 200 - application/json (markup) [expand]

    Example
    {
         "html" : "<h1>Hello World!</h1>"
     }

    The rendered markdown.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The markdown was invalid.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions preview rendered markdown.

/rest/api/1.0/migration/imports/{jobId}/cancel

resource-wide template parameters
parametervaluedescription

jobId

long

the ID of the job to cancel

Methods

POST

Requests the cancellation of an import job.

The request to cancel a job will be processed successfully if the job is actually still running. If it has already finished (successfully or with errors) or if it has already been canceled before, then an error will be returned.

Note that import jobs are not canceled as instantaneously as export jobs. Rather, once the request has been accepted, there are a number of checkpoints at which the job will actually apply it and stop. This is to keep the system in a reasonably consistent state:

  • After the current fork hierarchy has been imported and verified.
  • Before the next repository is imported.
  • Before the next pull request is imported.

A client should always actively query the job status to confirm that a job has been successfully canceled.

The authenticated user must have ADMIN permission or higher to call this resource.

Example response representations:

  • 204 [expand]

    The job has successfully been marked for cancellation.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to cancel this job.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified job does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The job was in a state that does not allow cancellation, e.g. it has already finished.

/rest/api/1.0/migration/exports/{jobId}

resource-wide template parameters
parametervaluedescription

jobId

long

the ID of the job

Methods

GET

Gets the details, including the current status and progress, of the export job identified by the given ID.

The authenticated user must have ADMIN permission or higher to call this resource.

Example response representations:

  • 200 - application/json (job) [expand]

    Example
    {"id":1,"nodeId":"1bec7499-077a-4b58-b27c-996a9c2187a4","progress":{"message":"Working on it...","percentage":42},"startDate":1497657601000,"state":"RUNNING","type":"com.atlassian.bitbucket.migration.export","updateDate":1497657603000,"initiator":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}}

    The job, including status and progress information.

  • 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 information about this job.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified job does not exist.

/rest/api/1.0/migration/exports/{jobId}/cancel

resource-wide template parameters
parametervaluedescription

jobId

long

the ID of the job to cancel

Methods

POST

Requests the cancellation of an export job.

The request to cancel a job will be processed successfully if the job is actually still running. If it has already finished (successfully or with errors) or if it has already been canceled before, then an error will be returned.

There might be a small delay between accepting the request and actually cancelling the job. In most cases, the delay will be close to instantaneously. In the unlikely case of communication issues across a cluster, it can however take a few seconds to cancel a job.

A client should always actively query the job status to confirm that a job has been successfully canceled.

The authenticated user must have ADMIN permission or higher to call this resource.

Example response representations:

  • 204 [expand]

    The job has successfully been marked for cancellation.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to cancel this job.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified job does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The job was in a state that does not allow cancellation, e.g. it has already finished.

/rest/api/1.0/migration/exports/{jobId}/messages

resource-wide template parameters
parametervaluedescription

jobId

long

the ID of the job

Methods

GET

/rest/api/1.0/migration/exports/{jobId}/messages?severity&subject

This is a paged API.

Gets the messages generated by the job.

Without any filter, all messages will be returned, but the response can optionally be filtered for the following severities. The severity parameter can be repeated to include multiple severities in one response.

  • INFO
  • WARN
  • ERROR

The authenticated user must have ADMIN permission or higher to call this resource.

request query parameters
parametervaluedescription

severity

string

the severity to include in the results

subject

string

the subject

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":3,"limit":25,"isLastPage":true,"values":[{"createdDate":1497657601250,"id":617,"severity":"INFO","subject":"job","text":"Something of interest happened"},{"createdDate":1497657601500,"id":618,"severity":"WARN","subject":"repo: PRJ/my-repo","text":"Something did not work perfectly"},{"createdDate":1497657601750,"id":619,"severity":"ERROR","subject":"job","text":"Something has failed"}],"start":0}

    The messages generated by this job.

  • 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 information about this job.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified job does not exist.

/rest/api/1.0/migration/imports/{jobId}/messages

resource-wide template parameters
parametervaluedescription

jobId

long

the ID of the job

Methods

GET

/rest/api/1.0/migration/imports/{jobId}/messages?severity&subject

This is a paged API.

Gets the messages generated by the job.

Without any filter, all messages will be returned, but the response can optionally be filtered for the following severities. The severity parameter can be repeated to include multiple severities in one response.

  • INFO
  • WARN
  • ERROR

The authenticated user must have ADMIN permission or higher to call this resource.

request query parameters
parametervaluedescription

severity

string

the severity to include in the results

subject

string

the subject

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":3,"limit":25,"isLastPage":true,"values":[{"createdDate":1497657601250,"id":617,"severity":"INFO","subject":"job","text":"Something of interest happened"},{"createdDate":1497657601500,"id":618,"severity":"WARN","subject":"repo: PRJ/my-repo","text":"Something did not work perfectly"},{"createdDate":1497657601750,"id":619,"severity":"ERROR","subject":"job","text":"Something has failed"}],"start":0}

    The messages generated by this job.

  • 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 information about this job.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified job does not exist.

/rest/api/1.0/migration/exports/preview

Methods

POST

Enumerates the projects and repositories that would be exported for a given export request.

All affected repositories will be enumerated explicitly, and while projects are listed as individual items in responses from this endpoint, their presence does not imply that all their repositories are included.

While this endpoint can be used to verify that all selectors in the request apply as intended, it should be noted that a subsequent, actual export might contain a different set of repositories, as they might have been added or deleted in the meantime.

Note that the overall response from this endpoint can become very large when a lot of repositories end up in the selection. This is why the server is streaming the response while it is being generated (as opposed to creating it in memory and then sending it all at once) and it can be consumed in a streaming way, too.

Also, due to the potential size of the response, projects and repositories are listed with fewer details than in other REST responses.

For a more detailed description of selectors, see the endpoint documentation for starting an export.

The authenticated user must have ADMIN permission or higher to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"repositoriesRequest":{"includes":[{"projectKey":"PRJ","slug":"my-repo"}]}}

Example response representations:

  • 200 - application/json (scopes) [expand]

    Example
    {"scopes":[{"key":"PRJ","id":1,"name":"My Cool Project","public":true,"type":"NORMAL","scope":"PROJECT"},{"slug":"my-repo","id":1,"name":"My repo","forkable":true,"public":true,"project":"PRJ","scope":"REPOSITORY"}]}

    The effectively selected projects and repositories.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to generate a preview.

/rest/api/1.0/migration/exports

Methods

POST

Starts a background job that exports the selected repositories.

Only 2 concurrent exports are supported per cluster node. If a request ends up on a node that is already running that many export jobs, the request will be rejected and an error returned.

The response includes a description of the job that has been started, and its ID can be used to query these details again, including the current progress, warnings and errors that occurred while processing the job, and to interrupt and cancel the execution of this job.

The request to start an export is similar to the one for previewing an export. Additionally, it accepts an optional parameter, exportLocation, which can be used to specify a relative path within data/migration/export in the shared home directory. No locations outside of that directory will be accepted for exports.

There are essentially three ways to select repositories for export. Regardless of which you use, a few general rules apply:

  • You can supply a list of selectors. The selection will be additive.
  • Repositories that are selected more than once due to overlapping selectors will be de-duplicated and effectively exported only once.
  • For every selected repository, its full fork hierarchy will be considered selected, even if parts of that hierarchy would otherwise not be matched by the provided selectors. For example, when you explicitly select a single repository only, but that repository is a fork, then its origin will be exported (and eventually imported), too.

Now, a single repository can be selected like this:

     {
        "projectKey": "PRJ",
        "slug": "my-repo"
     }
     

Second, all repositories in a specific project can be selected like this:

     {
        "projectKey": "PRJ",
        "slug": *"
     }
     

And third, all projects and repositories in the system would be selected like this:

     {
        "projectKey": "*",
        "slug": *"
     }
     

The authenticated user must have ADMIN permission or higher to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"exportLocation":"example/sub/directory","repositoriesRequest":{"includes":[{"projectKey":"PRJ","slug":"my-repo"}]}}

Example response representations:

  • 200 - application/json (job) [expand]

    Example
    {"id":1,"nodeId":"1bec7499-077a-4b58-b27c-996a9c2187a4","progress":{"message":"Working on it...","percentage":42},"startDate":1497657601000,"state":"RUNNING","type":"com.atlassian.bitbucket.migration.export","updateDate":1497657603000,"initiator":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}}

    Details about the export job.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to start an an export.

  • 503 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The export could not be started because the limit of concurrent migration jobs has been reached.

/rest/api/1.0/migration/imports

Methods

POST

Starts a background job that imports the specified archive.

Only 1 import at a time is supported per cluster. If another request is made while an import is already running, the request will be rejected and an error returned.

The path in the request must point to a valid archive file. The file must be located within the data/migration/import directory in the shared home directory.

The authenticated user must have ADMIN permission or higher to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"archivePath":"Bitbucket_export_1.tar"}

Example response representations:

  • 200 - application/json (job) [expand]

    Example
    {"id":1,"nodeId":"1bec7499-077a-4b58-b27c-996a9c2187a4","progress":{"message":"Working on it...","percentage":42},"startDate":1497657601000,"state":"RUNNING","type":"com.atlassian.bitbucket.migration.import","updateDate":1497657603000,"initiator":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}}

    Details about the export job.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to start an an import.

  • 503 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The import could not be started because the limit of concurrent migration jobs has been reached.

/rest/api/1.0/migration/imports/{jobId}

resource-wide template parameters
parametervaluedescription

jobId

long

the ID of the job

Methods

GET

Gets the details, including the current status and progress, of the import job identified by the given ID.

The authenticated user must have ADMIN permission or higher to call this resource.

Example response representations:

  • 200 - application/json (job) [expand]

    Example
    {"id":1,"nodeId":"1bec7499-077a-4b58-b27c-996a9c2187a4","progress":{"message":"Working on it...","percentage":42},"startDate":1497657601000,"state":"RUNNING","type":"com.atlassian.bitbucket.migration.import","updateDate":1497657603000,"initiator":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}}

    The job, including status and progress information.

  • 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 information about this job.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified job does not exist.

/rest/api/1.0/profile/recent/repos

Methods

GET

/rest/api/1.0/profile/recent/repos?permission

This is a paged API.

Retrieve a page of recently accessed repositories for the currently authenticated user.

Repositories are ordered from most recently to least recently accessed.

Only authenticated users may call this resource.

request query parameters
parametervaluedescription

permission

string

(optional) if specified, it must be a valid repository permission level name and will limit the resulting repository list to ones that the requesting user has the specified permission level to. If not specified, the default REPO_READ permission level will be assumed.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}}],"start":0}

    A page of recently accessed repositories.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The permission level is unknown or not related to repository.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The request is unauthenticated.

/rest/api/1.0/projects

Methods

POST

Create a new project.

To include a custom avatar for the project, the project definition should contain an additional attribute with the key avatar and the value a data URI containing Base64-encoded image data. The URI should be in the following format:

     data:(content type, e.g. image/png);base64,(data)
 
If the data is not Base64-encoded, or if a character set is defined in the URI, or the URI is otherwise invalid, project creation will fail.

The authenticated user must have PROJECT_CREATE permission to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"key":"PRJ","name":"My Cool Project","description":"The description for my cool project.","avatar":"data:image/png;base64,<base64-encoded-image-data>"}

Example response representations:

  • 201 - application/json (project) [expand]

    Example
    {"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"}]}}

    The newly created project.

  • 400 - application/json (errors) [expand]

    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 project was not created due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to create a project.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The project key or name is already in use.

GET

/rest/api/1.0/projects?name&permission

This is a paged API.

Retrieve a page of projects.

Only projects for which the authenticated user has the PROJECT_VIEW permission will be returned.

request query parameters
parametervaluedescription

name

string

name to filter by

permission

string

permission to filter by

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"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"}]}}],"start":0}

    A page of projects.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The permission level is unknown or not related to projects.

/rest/api/1.0/projects/{projectKey}

Methods

DELETE

Delete the project matching the supplied projectKey.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Example response representations:

  • 204 [expand]

    The project matching the supplied projectKey was 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 project.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The project can not be deleted as it contains repositories.

PUT

Update the project matching the projectKey supplied in the resource path.

To include a custom avatar for the updated project, the project definition should contain an additional attribute with the key avatar and the value a data URI containing Base64-encoded image data. The URI should be in the following format: data:(content type, e.g. image/png);base64,(data) If the data is not Base64-encoded, or if a character set is defined in the URI, or the URI is otherwise invalid, project creation will fail.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"key":"PRJ","name":"My Cool Project","description":"The description for my cool project.","avatar":"data:image/png;base64,<base64-encoded-image-data>"}

Example response representations:

  • 200 - application/json (project) [expand]

    Example
    {"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"}]}}

    The updated project. The project's key was not updated.

  • 201 - application/json (project) [expand]

    Example
    {"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"}]}}

    The updated project. The project's key was updated.

  • 400 - application/json (errors) [expand]

    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 project was not updated due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update 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

Retrieve the project matching the supplied projectKey.

The authenticated user must have PROJECT_VIEW permission for the specified project to call this resource.

Example response representations:

  • 200 - application/json (project) [expand]

    Example
    {"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"}]}}

    The project matching the supplied projectKey.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the project.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project does not exist.

/rest/api/1.0/projects/{projectKey}/avatar.png

Methods

GET

/rest/api/1.0/projects/{projectKey}/avatar.png?s

Retrieve the avatar for the project matching the supplied projectKey.

The authenticated user must have PROJECT_VIEW permission for the specified project to call this resource.

request query parameters
parametervaluedescription

s

int

Default: 0

The desired size of the image. The server will return an image as close as possible to the specified size.

Example response representations:

  • 200 - image/png [expand]

    The avatar of the project matching the supplied projectKey.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the project.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project does not exist.

POST

Update the avatar for the project matching the supplied projectKey.

This resource accepts POST multipart form data, containing a single image in a form-field named 'avatar'.

There are configurable server limits on both the dimensions (1024x1024 pixels by default) and uploaded file size (1MB by default). Several different image formats are supported, but PNG and JPEG are preferred due to the file size limit.

This resource has Cross-Site Request Forgery (XSRF) protection. To allow the request to pass the XSRF check the caller needs to send an X-Atlassian-Token HTTP header with the value no-check.

An example curl request to upload an image name 'avatar.png' would be:

 curl -X POST -u username:password -H "X-Atlassian-Token: no-check" http://example.com/rest/api/1.0/projects/STASH/avatar.png -F avatar=@avatar.png
 

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Example response representations:

  • 201 [expand]

    The avatar was uploaded successfully.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update the project.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project does not exist.

/rest/api/1.0/projects/{projectKey}/permissions/groups

Methods

GET

/rest/api/1.0/projects/{projectKey}/permissions/groups?filter

This is a paged API.

Retrieve a page of groups that have been granted at least one permission for the specified project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

request query parameters
parametervaluedescription

filter

string

if specified only group names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"group":{"name":"group_a"},"permission":"ADMIN"}],"start":0}

    A page of groups and their highest permissions for the specified project.

  • 401 [expand]

    The currently authenticated user is not a project administrator for the specified project.

  • 404 [expand]

    The specified project does not exist.

PUT

/rest/api/1.0/projects/{projectKey}/permissions/groups?permission&name

Promote or demote a group's permission level for the specified project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource. In addition, a user may not demote a group's permission level if their own permission level would be reduced as a result.

request query parameters
parametervaluedescription

permission

string

The permission to grant. See the [permissions documentation](https://confluence.atlassian.com/display/BitbucketServer/Using+project+permissions) for a detailed explanation of what each permission entails. Available project permissions are:

  • PROJECT_READ
  • PROJECT_WRITE
  • PROJECT_ADMIN

name

string

the names of the groups

Example response representations:

  • 204 [expand]

    The requested permission was granted.

  • 400 - application/json (errors) [expand]

    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 was malformed or the specified permission does not exist.

  • 401 [expand]

    The currently authenticated user is not an administrator for the specified project.

  • 403 [expand]

    The action was disallowed as it would reduce the currently authenticated user's permission level.

  • 404 [expand]

    The specified project or group does not exist.

DELETE

/rest/api/1.0/projects/{projectKey}/permissions/groups?name

Revoke all permissions for the specified project for a group.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

In addition, a user may not revoke a group's permissions if it will reduce their own permission level.

request query parameters
parametervaluedescription

name

string

the name of the group

Example response representations:

  • 204 [expand]

    All project permissions were revoked from the group for the specified project.

  • 401 [expand]

    The currently authenticated user is not an administrator of the specified project.

  • 404 [expand]

    The specified project or group does not exist.

  • 409 [expand]

    The action was disallowed as it would reduce the currently authenticated user's permission level.

/rest/api/1.0/projects/{projectKey}/permissions/groups/none

Methods

GET

/rest/api/1.0/projects/{projectKey}/permissions/groups/none?filter

This is a paged API.

Retrieve a page of groups that have no granted permissions for the specified project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

request query parameters
parametervaluedescription

filter

string

if specified only group names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"group-a","deletable":true}],"start":0}

    A page of groups that have not been granted any permissions for the specified project.

  • 401 [expand]

    The currently authenticated user is not a project administrator for the specified project.

  • 404 [expand]

    The specified project does not exist.

/rest/api/1.0/projects/{projectKey}/permissions/users

Methods

GET

/rest/api/1.0/projects/{projectKey}/permissions/users?filter

This is a paged API.

Retrieve a page of users that have been granted at least one permission for the specified project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

request query parameters
parametervaluedescription

filter

string

if specified only user names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"permission":"ADMIN"}],"start":0}

    A page of users and their highest permissions for the specified project.

  • 401 [expand]

    The currently authenticated user is not a project administrator for the specified project.

  • 404 [expand]

    The specified project does not exist.

PUT

/rest/api/1.0/projects/{projectKey}/permissions/users?name&permission

Promote or demote a user's permission level for the specified project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource. In addition, a user may not reduce their own permission level unless they have a global permission that already implies that permission.

request query parameters
parametervaluedescription

name

string

the names of the users

permission

string

the permission to grant. See the [permissions documentation](https://confluence.atlassian.com/display/BitbucketServer/Using+project+permissions) for a detailed explanation of what each permission entails. Available project permissions are:

  • PROJECT_READ
  • PROJECT_WRITE
  • PROJECT_ADMIN

Example response representations:

  • 204 [expand]

    The requested permission was granted.

  • 400 [expand]

    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 was malformed or the specified permission does not exist.

  • 401 [expand]

    The currently authenticated user is not an administrator for the specified project.

  • 403 [expand]

    The action was disallowed as it would reduce the currently authenticated user's permission level.

  • 404 [expand]

    The specified project or user does not exist.

DELETE

/rest/api/1.0/projects/{projectKey}/permissions/users?name

Revoke all permissions for the specified project for a user.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

In addition, a user may not revoke their own project permissions if they do not have a higher global permission.

request query parameters
parametervaluedescription

name

string

the name of the user

Example response representations:

  • 204 [expand]

    All project permissions were revoked from the user for the specified project.

  • 401 [expand]

    The currently authenticated user is not an administrator of the specified project.

  • 404 [expand]

    The specified project or group does not exist.

  • 409 [expand]

    The action was disallowed as it would reduce the currently authenticated user's permission level.

/rest/api/1.0/projects/{projectKey}/permissions/users/none

Methods

GET

/rest/api/1.0/projects/{projectKey}/permissions/users/none?filter

This is a paged API.

Retrieve a page of licensed users that have no granted permissions for the specified project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

request query parameters
parametervaluedescription

filter

string

if specified only user names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"group-a","deletable":true}],"start":0}

    A page of users that have not been granted any permissions for the specified project.

  • 401 [expand]

    The currently authenticated user is not a project administrator for the specified project.

  • 404 [expand]

    The specified project does not exist.

/rest/api/1.0/projects/{projectKey}/permissions/{permission}/all

resource-wide template parameters
parametervaluedescription

permission

string

the permission to grant Available project permissions are:

  • PROJECT_READ
  • PROJECT_WRITE
  • PROJECT_ADMIN

Methods

GET

Check whether the specified permission is the default permission (granted to all users) for a project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

Example response representations:

  • 200 - application/json (permitted) [expand]

    Example
    {"permitted":true}

    A simple entity indicating whether the specified permission is the default permission for this project.

  • 400 [expand]

    The request was malformed or the specified permission does not exist.

  • 401 [expand]

    The currently authenticated user is not an administrator of the specified project.

  • 404 [expand]

    The specified project does not exist.

POST

/rest/api/1.0/projects/{projectKey}/permissions/{permission}/all?allow

Grant or revoke a project permission to all users, i.e. set the default permission.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

request query parameters
parametervaluedescription

allow

boolean

true to grant the specified permission to all users, or false to revoke it

Example response representations:

  • 204 [expand]

    The requested permission was successfully granted or revoked.

  • 400 [expand]

    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 was malformed or the specified permission does not exist.

  • 401 [expand]

    The currently authenticated user is not an administrator of the specified project.

  • 404 [expand]

    The specified project does not exist.

/rest/api/1.0/projects/{projectKey}/repos

resource-wide template parameters
parametervaluedescription

projectKey

string

the parent project key

Methods

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Create a new repository. Requires an existing project in which this repository will be created. The only parameters which will be used are name and scmId.

The authenticated user must have PROJECT_ADMIN permission for the context project to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"name":"My repo","scmId":"git","forkable":true,"defaultBranch":"main"}

Example response representations:

  • 201 - application/json (repository) [expand]

    Example
    {"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}}

    The newly created repository.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository was not created due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to create a repository.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    A repository with same name already exists.

GET

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve repositories from the project corresponding to the supplied projectKey.

The authenticated user must have REPO_READ permission for the specified project to call this resource.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}}],"start":0}

    The repositories matching the supplied projectKey.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to see the specified project.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}

resource-wide template parameters
parametervaluedescription

projectKey

string

the parent project key

projectKey

string

the parent project key

repositorySlug

string

the repository slug

Methods

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Schedule the repository matching the supplied projectKey and repositorySlug to be deleted. If the request repository is not present

The authenticated user must have sufficient permissions specified by the repository delete policy to call this resource. The default permission required is REPO_ADMIN permission.

Example response representations:

  • 202 - application/json (message) [expand]

    Example
    {"context":null,"message":"Repository scheduled for deletion.","exceptionName":null}

    The repository has been scheduled for deletion.

  • 204 [expand]

    No repository matching the supplied projectKey and repositorySlug was found.

  • 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 repository.

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Create a new repository forked from an existing repository.

The JSON body for this POST is not required to contain any properties. Even the name may be omitted. The following properties will be used, if provided:

  • "name":"Fork name" - Specifies the forked repository's name
    • Defaults to the name of the origin repository if not specified
  • "defaultBranch":"main" - Specifies the forked repository's default branch
    • Defaults to the origin repository's default branch if not specified
  • "project":{"key":"TARGET_KEY"} - Specifies the forked repository's target project by key
    • Defaults to the current user's personal project if not specified

The authenticated user must have REPO_READ permission for the specified repository and PROJECT_ADMIN on the target project to call this resource. Note that users always have PROJECT_ADMIN permission on their personal projects.

Example request representations:

  • application/json [expand]

    Example
    {"slug":"my-repo","name":null,"project":{"key":"PRJ"},"defaultBranch":"main"}

Example response representations:

  • 201 - application/json (repository) [expand]

    Example
    {"slug":"my-repo","id":2,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","scmId":"git","state":"AVAILABLE","statusMessage":"Available","forkable":true,"origin":{"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}},"project":{"key":"~JDOE","id":2,"name":"John Doe","type":"PERSONAL","links":{"self":[{"href":"http://link/to/project"}]}},"links":{"clone":[{"href":"https://<baseURL>/scm/JDOE/my-repo.git","name":"http"},{"href":"ssh://git@<baseURL>/JDOE/my-repo.git","name":"ssh"}],"self":[{"href":"http://link/to/repository"}]}}

    The newly created fork.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    A validation error prevented the fork from being created. Possible validation errors include: The name or slug for the fork collides with another repository in the target project; an SCM type was specified in the JSON body; a project was specified in the JSON body without a "key" property.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to create a fork.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist, or, if a target project was specified, the target project does not exist.

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the repository matching the supplied projectKey and repositorySlug.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Example response representations:

  • 200 - application/json (repository) [expand]

    Example
    {"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}}

    The repository which matches the supplied projectKey and repositorySlug.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to see the specified repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Update the repository matching the repositorySlug supplied in the resource path.

The repository's slug is derived from its name. If the name changes the slug may also change.

This resource can be used to change the repository's default branch by specifying a new default branch in the request. For example: "defaultBranch":"main"

This resource can be used to move the repository to a different project by specifying a new project in the request. For example: "project":{"key":"NEW_KEY"}

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"name":"My repo","forkable":false,"project":{"key":"PRJ"},"public":true,"defaultBranch":"main"}

Example response representations:

  • 201 - application/json (repository) [expand]

    Example
    {"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}}

    The updated repository.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository was not updated due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update a repository

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    A repository with same name as the target already exists

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/contributing

resource-wide template parameters
parametervaluedescription

projectKey

string

the parent project key

Methods

HEAD

Example response representations:

  • application/json; charset=UTF-8 [expand]

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/contributing?at&hardwrap&htmlEscape&includeHeadingId&markup

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieves the contributing guidelines for the repository, if they've been defined.

This checks the repository for a

CONTRIBUTING
file, optionally with an
md
or
txt
extension, and, if found, streams it. By default, the raw content of the file is streamed. Appending
?markup
to the URL will stream an HTML-rendered version instead.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

at

string

a specific commit or ref to retrieve the guidelines at, or the default branch if not specified

hardwrap

string

(Optional) Whether the markup implementation should convert newlines to breaks. If not specified, the value of the markup.render.hardwrap property, which is true by default, will be used

htmlEscape

string

(Optional) true if HTML should be escaped in the input markup, false otherwise. If not specified, the value of the markup.render.html.escape property, which is true by default, will be used

includeHeadingId

string

(Optional) true if headings should contain an ID based on the heading content. If not specified, the value of the markup.render.headerids property, which is false by default, will be used

markup

string

if present or "true", triggers the raw content to be markup-rendered and returned as HTML; otherwise, if not specified, or any value other than "true", the content is streamed without markup

Example response representations:

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/default-branch

resource-wide template parameters
parametervaluedescription

projectKey

string

the parent project key

Methods

GET

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieves the repository's configured default branch.

Every repository has a configured default branch, but that branch may not actually exist in the repository. For example, a newly-created repository will have a configured default branch even though no branches have been pushed yet.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"id":"refs/heads/main","displayId":"main","type":"BRANCH"}

    The configured default branch 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 read the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist, or its configured default branch does not exist.

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Update the default branch of a repository.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"id":"refs/heads/main"}

Example response representations:

  • 204 [expand]

    The default branch was updated.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user does not have permission to modify the default branch.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/forks

resource-wide template parameters
parametervaluedescription

projectKey

string

the parent project key

Methods

GET

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve repositories which have been forked from this one. Unlike {@link #getRelatedRepositories(Repository, PageRequest) related repositories}, this only looks at a given repository's direct forks. If those forks have themselves been the origin of more forks, such "grandchildren" repositories will not be retrieved.

Only repositories to which the authenticated user has REPO_READ permission will be included, even if other repositories have been forked from this one.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"slug":"my-repo","id":2,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","scmId":"git","state":"AVAILABLE","statusMessage":"Available","forkable":true,"origin":{"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}},"project":{"key":"~JDOE","id":2,"name":"John Doe","type":"PERSONAL","links":{"self":[{"href":"http://link/to/project"}]}},"links":{"clone":[{"href":"https://<baseURL>/scm/JDOE/my-repo.git","name":"http"},{"href":"ssh://git@<baseURL>/JDOE/my-repo.git","name":"ssh"}],"self":[{"href":"http://link/to/repository"}]}}],"start":0}

    A page of repositories related to the request 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 see the request repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The request repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/license

resource-wide template parameters
parametervaluedescription

projectKey

string

the parent project key

Methods

HEAD

Example response representations:

  • application/json; charset=UTF-8 [expand]

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/license?at&hardwrap&htmlEscape&includeHeadingId&markup

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieves the license for the repository, if it's been defined.

This checks the repository for a

LICENSE
file, optionally with an
md
or
txt
extension, and, if found, streams it. By default, the raw content of the file is streamed. Appending
?markup
to the URL will stream an HTML-rendered version instead.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

at

string

a specific commit or ref to retrieve the license at, or the default branch if not specified

hardwrap

string

(Optional) Whether the markup implementation should convert newlines to breaks. If not specified, the value of the markup.render.hardwrap property, which is true by default, will be used

htmlEscape

string

(Optional) true if HTML should be escaped in the input markup, false otherwise. If not specified, the value of the markup.render.html.escape property, which is true by default, will be used

includeHeadingId

string

(Optional) true if headings should contain an ID based on the heading content. If not specified, the value of the markup.render.headerids property, which is false by default, will be used

markup

string

if present or "true", triggers the raw content to be markup-rendered and returned as HTML; otherwise, if not specified, or any value other than "true", the content is streamed without markup

Example response representations:

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/readme

resource-wide template parameters
parametervaluedescription

projectKey

string

the parent project key

Methods

HEAD

Example response representations:

  • application/json; charset=UTF-8 [expand]

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/readme?at&hardwrap&htmlEscape&includeHeadingId&markup

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieves the README for the repository, if it's been defined.

This checks the repository for a

README
file, optionally with an
md
or
txt
extension, and, if found, streams it. By default, the raw content of the file is streamed. Appending
?markup
to the URL will stream an HTML-rendered version instead. Note that, when streaming HTML, relative URLs in the README will not work if applied relative to this URL.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

at

string

a specific commit or ref to retrieve the README at, or the default branch if not specified

hardwrap

string

(Optional) Whether the markup implementation should convert newlines to breaks. If not specified, the value of the markup.render.hardwrap property, which is true by default, will be used

htmlEscape

string

(Optional) true if HTML should be escaped in the input markup, false otherwise. If not specified, the value of the markup.render.html.escape property, which is true by default, will be used

includeHeadingId

string

(Optional) true if headings should contain an ID based on the heading content. If not specified, the value of the markup.render.headerids property, which is false by default, will be used

markup

string

if present or "true", triggers the raw content to be markup-rendered and returned as HTML; otherwise, if not specified, or any value other than "true", the content is streamed without markup

Example response representations:

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/recreate

resource-wide template parameters
parametervaluedescription

projectKey

string

the parent project key

Methods

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

If a create or fork operation fails, calling this method will clean up the broken repository and try again. The repository must be in an INITIALISATION_FAILED state.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Example response representations:

  • 201 - application/json (repository) [expand]

    Example
    {"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}}

    The newly created repository.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository was not created due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to create a repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/related

resource-wide template parameters
parametervaluedescription

projectKey

string

the parent project key

Methods

GET

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve repositories which are related to this one. Related repositories are from the same {@link Repository#getHierarchyId() hierarchy} as this repository.

Only repositories to which the authenticated user has REPO_READ permission will be included, even if more repositories are part of this repository's hierarchy.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"slug":"my-repo","id":2,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","scmId":"git","state":"AVAILABLE","statusMessage":"Available","forkable":true,"origin":{"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}},"project":{"key":"~JDOE","id":2,"name":"John Doe","type":"PERSONAL","links":{"self":[{"href":"http://link/to/project"}]}},"links":{"clone":[{"href":"https://<baseURL>/scm/JDOE/my-repo.git","name":"http"},{"href":"ssh://git@<baseURL>/JDOE/my-repo.git","name":"ssh"}],"self":[{"href":"http://link/to/repository"}]}}],"start":0}

    A page of repositories related to the request 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 see the request repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The request repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/archive

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/archive?at&filename&format&path&prefix

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Streams an archive of the repository's contents at the requested commit. If no at= commit is requested, an archive of the default branch is streamed.

The filename= query parameter may be used to specify the exact filename to include in the "Content-Disposition" header. If an explicit filename is not provided, one will be automatically generated based on what is being archived. Its format depends on the at= value:

  • No at= commit: <slug>-<default-branch-name>@<commit>.<format>; e.g. example-master@43c2f8a0fe8.zip
  • at=sha: <slug>-<at>.<format>; e.g. example-09bcbb00100cfbb5310fb6834a1d5ce6cac253e9.tar.gz
  • at=branchOrTag: <slug>-<branchOrTag>@<commit>.<format>; e.g. example-feature@bbb225f16e1.tar
    • If the branch or tag is qualified (e.g. refs/heads/master, the short name (master) will be included in the filename
    • If the branch or tag's short name includes slashes (e.g. release/4.6), they will be converted to hyphens in the filename (release-4.5)

Archives may be requested in the following formats by adding the format= query parameter:

  • zip: A zip file using standard compression (Default)
  • tar: An uncompressed tarball
  • tar.gz or tgz: A GZip-compressed tarball
The contents of the archive may be filtered by using the path= query parameter to specify paths to include. path= may be specified multiple times to include multiple paths.

The prefix= query parameter may be used to define a directory (or multiple directories) where the archive's contents should be placed. If the prefix does not end with /, one will be added automatically. The prefix is always treated as a directory; it is not possible to use it to prepend characters to the entries in the archive.

Archives of public repositories may be streamed by any authenticated or anonymous user. Streaming archives for non-public repositories requires an authenticated user with at least REPO_READ permission.

request query parameters
parametervaluedescription

at

string

the commit to stream an archive of; if not supplied, an archive of the default branch is streamed

filename

string

a filename to include the "Content-Disposition" header

format

string

the format to stream the archive in; must be one of: zip, tar, tar.gz or tgz

path

string

paths to include in the streamed archive; may be repeated to include multiple paths

prefix

string

a prefix to apply to all entries in the streamed archive; if the supplied prefix does not end with a trailing /, one will be added automatically

Example response representations:

  • 200 - application/octet-stream; application/x-tar (archive) [expand]

    An archive or the requested commit, in zip, tar or gzipped-tar format.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The requested format is not supported.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist or does not contain the at commit.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/attachments/{attachmentId}

resource-wide template parameters
parametervaluedescription

attachmentId

long

the attachment ID

Methods

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Delete an attachment.

The user must be authenticated and have REPO_ADMIN permission for the specified repository.

Example response representations:

  • 204 - application/json [expand]
  • 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 attachment

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The attachment does not exist

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the attachment.

The authenticated user must have REPO_READ permission for the specified repository that is associated to the attachment.

request header parameters
parametervaluedescription

User-Agent

string

the User-Agent header information

Example response representations:

  • 200 - specific attachment media type [expand]

    the attachment

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The user is currently not authenticated

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The attachment does not exist

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/attachments/{attachmentId}/metadata

resource-wide template parameters
parametervaluedescription

attachmentId

long

the attachment ID

Methods

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Delete attachment metadata.

The user must be authenticated and have REPO_ADMIN permission for the specified repository.

Example response representations:

  • 204 - application/json [expand]
  • 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 attachment metadata

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The attachment or the attachment metadata does not exist

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the attachment metadata.

The authenticated user must have REPO_READ permission for the specified repository that is associated to the attachment that has the attachment metadata.

Example response representations:

  • 200 - application/json (metadata) [expand]

    Example
    {"id":1,"metadata":"{\\\"A\\\":\\\"B\\\"}","url":"test.com/test"}

    The attachment metadata

  • 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 attachment metadata

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The attachment or the attachment metadata does not exist

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Save attachment metadata.

The authenticated user must have REPO_READ permission for the specified repository that is associated to the attachment that has the attachment metadata.

Example request representations:

  • application/json [expand]

    Example
    any valid JSON content

Example response representations:

  • 200 - application/json (metadata) [expand]

    Example
    the valid JSON content

    The attachment metadata

  • 400 - application/json (errors) [expand]

    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 supplied content is not valid JSON

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to save the attachment metadata

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository or the attachment does not exist

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/branches

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/branches?base&details&filterText&orderBy&boostMatches

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the branches matching the supplied filterText param.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

base

string

base branch or tag to compare each branch to (for the metadata providers that uses that information)

details

boolean

whether to retrieve plugin-provided metadata about each branch

filterText

string

the text to match on

orderBy

string

ordering of refs either ALPHABETICAL (by name) or MODIFICATION (last updated)

boostMatches

boolean

controls whether exact and prefix matches will be boosted to the top

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"id":"refs/heads/main","displayId":"main","type":"BRANCH","latestCommit":"8d51122def5632836d1cb1026e879069e10a1e13","latestChangeset":"8d51122def5632836d1cb1026e879069e10a1e13","isDefault":true}],"start":0}

    The branches matching the supplied filterText.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to read the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Creates a branch using the information provided in the {@link RestCreateBranchRequest request}

The authenticated user must have REPO_WRITE permission for the context repository to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"name":"my-branch","startPoint":"8d351a10fb428c0c1239530256e21cf24f136e73","message":"This is my branch"}

Example response representations:

  • 200 - application/json (branch) [expand]

    Example
    {"id":"refs/heads/main","displayId":"main","type":"BRANCH","latestCommit":"8d51122def5632836d1cb1026e879069e10a1e13","latestChangeset":"8d51122def5632836d1cb1026e879069e10a1e13","isDefault":true}

    The created branch

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to write 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/api/1.0/projects/{projectKey}/repos/{repositorySlug}/branches/default

Methods

GET

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieves the repository's default branch, if it has been created. If the repository is empty, 204 No Content will be returned. For non-empty repositories, if the configured default branch has not yet been created a 404 Not Found will be returned.

This URL is deprecated. Callers should use GET /projects/{key}/repos/{slug}/default-branch instead, which allows retrieving the configured default branch even if the ref has not been created yet.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"id":"refs/heads/main","displayId":"main","type":"BRANCH","latestCommit":"8d51122def5632836d1cb1026e879069e10a1e13","latestChangeset":"8d51122def5632836d1cb1026e879069e10a1e13","isDefault":true}

    The configured default branch for the repository.

  • 204 [expand]

    The repository is empty, and has no default branch.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to read the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist, or its configured default branch does not exist.

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Update the default branch of a repository.

This URL is deprecated. Callers should use PUT /projects/{key}/repos/{slug}/default-branch instead.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"id":"refs/heads/main"}

Example response representations:

  • 204 [expand]

    The operation was successful

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update 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/api/1.0/projects/{projectKey}/repos/{repositorySlug}/browse

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/browse?at&size&type&blame&noContent

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of content for a file path at a specified revision.

Responses from this endpoint vary widely depending on the query parameters. The example JSON is for a request that does not use size, type, blame or noContent.

  1. size will return a response like {"size":10000}
  2. type will return a response like {"type":"FILE"}, where possible values are "DIRECTORY", "FILE" and "SUBMODULE"
  3. blame without noContent will include blame for the lines of content returned on the page
  4. blame with noContent will omit file contents and only return blame for the requested lines
  5. noContent without blame is ignored and does nothing
The various parameters are "processed" in the above order. That means ?size=true&type=true will return a size response, not a type one; the type parameter will be ignored.

The blame and noContent query parameters are handled differently from size and type. For blame and noContent, the presence of the parameter implies "true" if no value is specified; size and and type both require an explicit =true or they're treated as "false".

  • ?blame is the same as ?blame=true
  • ?blame&noContent is the same as ?blame=true&noContent=true
  • ?size is the same as ?size=false
  • ?type is the same as ?type=false

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

at

string

Default:

the commit ID or ref to retrieve the content for

size

boolean

Default: false

if true only the size will be returned for the file path instead of the contents

type

boolean

Default: false

if true only the type will be returned for the file path instead of the contents

blame

string

if present and not equal to 'false', the blame will be returned for the file as well

noContent

string

if blame&noContent only the blame is retrieved instead of the contents

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"start":0,"lines":[{"text":"print('hello world')"}]}

    A page of contents from a file.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The path or until parameters were not supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/browse/{path:.*}

resource-wide template parameters
parametervaluedescription

path

string

Default:

the file path to retrieve content from

Methods

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Update the content of path, on the given repository and branch.

This resource accepts PUT multipart form data, containing the file in a form-field named content.

An example curl request to update 'README.md' would be:

 curl -X PUT -u username:password -F content=@README.md  -F 'message=Updated using file-edit REST API'
 -F branch=master -F  sourceCommitId=5636641a50b
  http://example.com/rest/api/latest/projects/PROJECT_1/repos/repo_1/browse/README.md
 
  • branch: the branch on which the path should be modified or created
  • content: the full content of the file at path
  • message: the message associated with this change, to be used as the commit message. Or null if the default message should be used.
  • sourceCommitId: the commit ID of the file before it was edited, used to identify if content has changed. Or null if this is a new file

The file can be updated or created on a new branch. In this case, the sourceBranch parameter should be provided to identify the starting point for the new branch and the branch parameter identifies the branch to create the new commit on.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0123a","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"WIP on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]}

    The newly created commit

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The branch or content parameters were not supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user does not have write permission for the given repository

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The file already exists when trying to create a file, or the given content does not modify the file, or the file has changed since the given sourceCommitId

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/browse/{path:.*}?at&size&type&blame&noContent

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of content for a file path at a specified revision.

Responses from this endpoint vary widely depending on the query parameters. The example JSON is for a request that does not use size, type, blame or noContent.

  1. size will return a response like {"size":10000}
  2. type will return a response like {"type":"FILE"}, where possible values are "DIRECTORY", "FILE" and "SUBMODULE"
  3. blame without noContent will include blame for the lines of content returned on the page
  4. blame with noContent will omit file contents and only return blame for the requested lines
  5. noContent without blame is ignored and does nothing
The various parameters are "processed" in the above order. That means ?size=true&type=true will return a size response, not a type one; the type parameter will be ignored.

The blame and noContent query parameters are handled differently from size and type. For blame and noContent, the presence of the parameter implies "true" if no value is specified; size and and type both require an explicit =true or they're treated as "false".

  • ?blame is the same as ?blame=true
  • ?blame&noContent is the same as ?blame=true&noContent=true
  • ?size is the same as ?size=false
  • ?type is the same as ?type=false

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

at

string

Default:

the commit ID or ref to retrieve the content for

size

boolean

Default: false

if true only the size will be returned for the file path instead of the contents

type

boolean

Default: false

if true only the type will be returned for the file path instead of the contents

blame

string

if present and not equal to 'false', the blame will be returned for the file as well

noContent

string

if blame&noContent only the blame is retrieved instead of the contents

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"start":0,"lines":[{"text":"print('hello world')"}]}

    A page of contents from a file.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The path or until parameters were not supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/changes

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/changes?since&until

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of changes made in a specified commit.

Note: The implementation will apply a hard cap (page.max.changes) and it is not possible to request subsequent content when that cap is exceeded.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

since

string

the commit to which until should be compared to produce a page of changes. If not specified the commit's first parent is assumed (if one exists)

until

string

the commit to retrieve changes for

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"contentId":"abcdef0123abcdef4567abcdef8987abcdef6543","fromContentId":"bcdef0123abcdef4567abcdef8987abcdef6543a","path":{"components":["new","path","to","file.txt"],"parent":"new/path/to","name":"file.txt","extension":"txt","toString":"new/path/to/file.txt"},"executable":false,"percentUnchanged":98,"type":"MOVE","nodeType":"FILE","srcPath":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"srcExecutable":false,"links":{"self":[{"href":"http://link/to/restchange"}]}}],"start":0}

    A page of changes

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The until parameter was not supplied

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository or the since or until parameters supplied does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits?followRenames&ignoreMissing&merges&path&since&until&withCounts&avatarSize&avatarScheme

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of commits from a given starting commit or "between" two commits. If no explicit commit is specified, the tip of the repository's default branch is assumed. commits may be identified by branch or tag name or by ID. A path may be supplied to restrict the returned commits to only those which affect that path.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

followRenames

boolean

Default: false

if true, the commit history of the specified file will be followed past renames. Only valid for a path to a single file.

ignoreMissing

boolean

Default: false

true to ignore missing commits, false otherwise

merges

string

if present, controls how merge commits should be filtered. Can be either exclude, to exclude merge commits, include, to include both merge commits and non-merge commits or only, to only return merge commits.

path

string

an optional path to filter commits by

since

string

the commit ID or ref (exclusively) to retrieve commits after

until

string

the commit ID (SHA1) or ref (inclusively) to retrieve commits before

withCounts

boolean

Default: false

optionally include the total number of commits and total number of unique authors

avatarSize

string

if present the service adds avatar URLs for commit authors. Should be an integer specifying the desired size in pixels. If the parameter is not present, avatar URLs will not be set

avatarScheme

string

the desired scheme for the avatar URL. If the parameter is not present URLs will use the same scheme as this request

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"id":"def0123abcdef4567abcdef8987abcdef6543abc","displayId":"def0123abcd","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"More work on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]}],"start":0,"authorCount":1,"totalCount":1}

    A page of commits.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    One of the supplied commit IDs or refs was invalid.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}

resource-wide template parameters
parametervaluedescription

commitId

string

the commit ID to retrieve

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}?path

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a single commit identified by its ID. In general, that ID is a SHA1. From 2.11, ref names like "refs/heads/master" are no longer accepted by this resource.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

path

string

an optional path to filter the commit by. If supplied the details returned may not be for the specified commit. Instead, starting from the specified commit, they will be the details for the first commit affecting the specified path.

Example response representations:

  • 200 - application/json (commit) [expand]

    Example
    {"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0123a","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"WIP on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]}

    A commit.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The supplied commit ID was invalid.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/builds

resource-wide template parameters
parametervaluedescription

commitId

string

full SHA1 of the commit (ex: e00cf62997a027bbf785614a93e2e55bb331d268)

Methods

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Store a build status.

The authenticated user must have REPO_READ permission for the repository that this build status is for. The request can also be made with anonymous 2-legged OAuth.

Example request representations:

  • */* [expand]

    Example
    {"key":"TEST-REP123","state":"SUCCESSFUL","url":"https://bamboo.url/browse/TEST-REP1-3","buildNumber":"3","description":"Unit test build","duration":1500000,"lastUpdated":1359075920,"name":"Database Matrix Tests","parent":"TEST-REP","ref":"refs/heads/master","testResults":{"failed":1,"skipped":8,"successful":0}}

Example response representations:

  • 204 [expand]

    The build status was posted

  • 400 - application/json (errors) [expand]

    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 build status was not added as the request was invalid. This could be because of a number of things:

    • an invalid commit hash was provided
    • build key was blank or longer than 255 characters
    • invalid branch was provided
    • invalid state was provided
    • build status url was blank or longer than 450 characters
    The specifics will be included in the error message.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to push a build status to this repository

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/builds?key

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Get a specific build status.

The authenticated user must have REPO_READ permission for the provided repository. The request can also be made with anonymous 2-legged OAuth.

request query parameters
parametervaluedescription

key

string

the key of the build status

Example response representations:

  • 200 - application/json (buildStatus) [expand]

    Example
    {"createdDate":1587533099278,"dateAdded":1587533699278,"description":"A description of the build goes here","key":"TEST-REP3","state":"SUCCESSFUL","name":"Database Matrix Tests","updatedDate":1587533699278,"url":"https://bamboo.example.com/browse/TEST-REP3","buildNumber":"3","commit":{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0123a","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"WIP on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]},"duration":15000,"parent":"TEST-REP","ref":"refs/heads/master","testResults":{"failed":1,"skipped":5,"successful":10}}

    The build status associated with the provided commit and key

  • 400 - application/json (errors) [expand]

    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 (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions this repository

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository, commit or build status does not exist

DELETE

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/builds?key

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Delete a specific build status.

The authenticated user must have REPO_ADMIN permission for the provided repository.

request query parameters
parametervaluedescription

key

string

the key of the build status

Example response representations:

  • 204 - application/json [expand]

    The build status associated with the provided commit and key has been deleted

  • 400 - application/json (errors) [expand]

    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 (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions this repository

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/changes

resource-wide template parameters
parametervaluedescription

commitId

string

the commit to retrieve changes for

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/changes?since&withComments

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of changes made in a specified commit.

Note: The implementation will apply a hard cap (page.max.changes) and it is not possible to request subsequent content when that cap is exceeded.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

since

string

the commit to which until should be compared to produce a page of changes. If not specified the commit's first parent is assumed (if one exists)

withComments

boolean

Default: true

true to apply comment counts in the changes (the default); otherwise, false to stream changes without comment counts

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"contentId":"abcdef0123abcdef4567abcdef8987abcdef6543","fromContentId":"bcdef0123abcdef4567abcdef8987abcdef6543a","path":{"components":["new","path","to","file.txt"],"parent":"new/path/to","name":"file.txt","extension":"txt","toString":"new/path/to/file.txt"},"executable":false,"percentUnchanged":98,"type":"MOVE","nodeType":"FILE","srcPath":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"srcExecutable":false,"links":{"self":[{"href":"http://link/to/restchange"}]}}],"start":0}

    A page of changes

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The until parameter was not supplied

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository or the since or until parameters supplied does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/comments

resource-wide template parameters
parametervaluedescription

commitId

string

the commit to which the comments must be anchored

Methods

POST

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/comments?since

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Add a new comment.

Comments can be added in a few places by setting different attributes:

General commit comment:

     {
         "text": "An insightful general comment on a commit."
     }
     
Reply to a comment:
     {
         "text": "A measured reply.",
         "parent": {
             "id": 1
         }
     }
     
General file comment:
     {
         "text": "An insightful general comment on a file.",
         "anchor": {
             "diffType": "COMMIT",
             "fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd",
             "path": "path/to/file",
             "srcPath": "path/to/file",
             "toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b"
         }
     }
     
File line comment:
     {
         "text": "A pithy comment on a particular line within a file.",
         "anchor": {
             "diffType": "COMMIT",
             "line": 1,
             "lineType": "CONTEXT",
             "fileType": "FROM",
             "fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd",
             "path": "path/to/file",
             "srcPath": "path/to/file",
             "toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b"
     }
     }
     
Note: general file comments are an experimental feature and may change in the near future!

For file and line comments, 'path' refers to the path of the file to which the comment should be applied and 'srcPath' refers to the path the that file used to have (only required for copies and moves). Also, fromHash and toHash refer to the sinceId / untilId (respectively) used to produce the diff on which the comment was added. Finally diffType refers to the type of diff the comment was added on.

For line comments, 'line' refers to the line in the diff that the comment should apply to. 'lineType' refers to the type of diff hunk, which can be:

  • 'ADDED' - for an added line;
  • 'REMOVED' - for a removed line; or
  • 'CONTEXT' - for a line that was unmodified but is in the vicinity of the diff.
'fileType' refers to the file of the diff to which the anchor should be attached - which is of relevance when displaying the diff in a side-by-side way. Currently the supported values are:
  • 'FROM' - the source file of the diff
  • 'TO' - the destination file of the diff
If the current user is not a participant the user is added as one and updated to watch the commit.

The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.

request query parameters
parametervaluedescription

since

string

for a merge commit, a parent can be provided to specify which diff the comments should be on. For a commit range, a sinceId can be provided to specify where the comments should be anchored from.

Example request representations:

  • application/json [expand]

    Example
    {"text":"An insightful comment.","parent":{"id":1,"severity":"NORMAL","state":"OPEN"},"anchor":{"line":1,"lineType":"CONTEXT","fileType":"FROM","path":"path/to/file","srcPath":"path/to/file"},"severity":"NORMAL","state":"OPEN"}

Example response representations:

  • 201 - application/json (comment) [expand]

    Example
    {"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}

    The newly created comment.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The comment was not created due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the commit, create a comment or watch the commit.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository, commit or parent comment. The missing entity will be specified in the error details.

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/comments?path&since

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieves the commit discussion comments that match the specified search criteria.

It is possible to retrieve commit discussion comments that are anchored to a range of commits by providing the sinceId that the comments anchored from.

The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.

request query parameters
parametervaluedescription

path

string

the path to the file on which comments were made

since

string

for a merge commit, a parent can be provided to specify which diff the comments are on. For a commit range, a sinceId can be provided to specify where the comments are anchored from.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"start":0}

    A page of comments that match the search criteria

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the comment

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository, or commit. The missing entity will be specified in the error details.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/comments/{commentId}

resource-wide template parameters
parametervaluedescription

commitId

string

the commit to which the comments must be anchored

commentId

long

the ID of the comment to retrieve

commitId

string

the full {@link Commit#getId() ID} of the commit within the repository

Methods

DELETE

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/comments/{commentId}?version

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Delete a commit comment. Anyone can delete their own comment. Only users with REPO_ADMIN and above may delete comments created by other users. Comments which have replies may not be deleted, regardless of the user's granted permissions.

The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.

request query parameters
parametervaluedescription

version

int

Default: -1

the expected version of the comment. This must match the server's version of the comment or the delete will fail. To determine the current version of the comment, the comment should be fetched from the server prior to the delete. Look for the 'version' attribute in the returned JSON structure.

Example response representations:

  • 204 [expand]

    The operation was successful

  • 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 comment.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository or commit. The missing entity will be specified in the error details.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The comment has replies or the version supplied does not match the comment's current version.

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Update a comment, with the following restrictions:

  • only the author of the comment may update the text of the comment
  • only the author of the comment or repository admins and above may update the other fields of a comment

Note: the supplied supplied JSON object must contain a version that must match the server's version of the comment or the update will fail. To determine the current version of the comment, the comment should be fetched from the server prior to the update. Look for the 'version' attribute in the returned JSON structure.

The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"version":0,"text":"A pithy comment.","severity":"NORMAL","state":"OPEN"}

Example response representations:

  • 201 - application/json (comment) [expand]

    Example
    {"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}

    The newly updated comment.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The comment was not updated due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the commit, update the comment or watch the commit.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository, commit or comment. The missing entity will be specified in the error details.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The comment version supplied does not match the current version.

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieves a commit discussion comment.

The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource.

Example response representations:

  • 200 - application/json (comment) [expand]

    Example
    {"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}

    The requested comment.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the comment

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository, commit or comment. The missing entity will be specified in the error details.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/deployments

resource-wide template parameters
parametervaluedescription

commitId

string

the commitId that was deployed as indicated by the path

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/deployments?key&environmentKey&deploymentSequenceNumber

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Get the deployment matching the specified {@link Repository}, key, environmentKey and deploymentSequenceNumber.

The user must have {@link com.atlassian.bitbucket.permission.Permission#REPO_READ}.

request query parameters
parametervaluedescription

key

string

the key of the deployment, as detailed by the query parameter

environmentKey

string

the key of the environment, as detailed by the query parameter

deploymentSequenceNumber

long

the sequence number of the deployment, as detailed by the query param

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"deploymentSequenceNumber":5,"description":"Production and mirror environments","displayName":"Production","environment":{"displayName":"US East Mirror","key":"us-east-mirror","type":"production","url":"https://foo-bar.production/us-east"},"fromCommit":{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"},"key":"PROD-MIR","lastUpdated":1646171633821,"repository":{"name":"My repo","scmId":"git","forkable":true,"defaultBranch":"main"},"state":"SUCCESSFUL","toCommit":{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"},"url":"http://example.ci.org/projects/PROJ/deploy/mirror-deploy/100"}

    The deployment

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    could not get the deployment because the request was invalid

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or deployment does not exist

DELETE

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/deployments?key&environmentKey&deploymentSequenceNumber

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Delete the deployment matching the specified {@link Repository}, key, environmentKey and deploymentSequenceNumber.

The user must have {@link com.atlassian.bitbucket.permission.Permission#REPO_ADMIN}.

request query parameters
parametervaluedescription

key

string

the key of the deployment, as detailed by the query parameter

environmentKey

string

the key of the environment, as detailed by the query parameter

deploymentSequenceNumber

long

the sequence number of the deployment, as detailed by the query parameter

Example response representations:

  • 204 [expand]

    the request has been processed

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    the deployment was not deleted because the request was invalid

  • 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 a deployment

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist

POST

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Create or update a deployment.

The authenticated user must have {@link com.atlassian.bitbucket.permission.Permission#REPO_READ} permission for the repository.

Example request representations:

  • */* [expand]

    Example
    {"deploymentSequenceNumber":2,"description":"2nd deployment of commit 44bca31f4be to US East production","displayName":"US East marketing website production","environment":{"displayName":"US East Mirror","key":"us-east-mirror","type":"production","url":"https://foo-bar.production/us-east"},"key":"marketing-us-prod","lastUpdated":1359075920,"state":"SUCCESSFUL","url":"https://my-dep-tool/marketing-us-prod/2"}

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"deploymentSequenceNumber":5,"description":"Production and mirror environments","displayName":"Production","environment":{"displayName":"US East Mirror","key":"us-east-mirror","type":"production","url":"https://foo-bar.production/us-east"},"fromCommit":{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"},"key":"PROD-MIR","lastUpdated":1646171633821,"repository":{"name":"My repo","scmId":"git","forkable":true,"defaultBranch":"main"},"state":"SUCCESSFUL","toCommit":{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"},"url":"http://example.ci.org/projects/PROJ/deploy/mirror-deploy/100"}

    The deployment was created

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    the deployment was not created because the request was invalid

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view 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/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/diff

resource-wide template parameters
parametervaluedescription

commitId

string

until ID, as indicated by the path

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/diff?autoSrcPath&contextLines&since&srcPath&whitespace

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Stream the diff between two provided revisions.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

autoSrcPath

boolean

Default: false

true to automatically try to find the source path when it's not provided, false otherwise. Requires the path to be provided.

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

since

string

the base revision to diff from. If omitted the parent revision of the until revision is used

srcPath

string

the source path for the file, if it was copied, moved or renamed

whitespace

string

optional whitespace flag which can be set to ignore-all

Example response representations:

  • 200 - text/plain [expand]

    A raw diff between two revisions.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The until parameter was not supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/diff?autoSrcPath&contextLines&since&srcPath&whitespace&withComments

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the diff between two provided revisions.

Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more truncated flags will be set to true on the "segments", "hunks" and "diffs" properties, as well as the top-level object, in the returned JSON response.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

autoSrcPath

boolean

Default: false

true to automatically try to find the source path when it's not provided, false otherwise. Requires the path to be provided.

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

since

string

the base revision to diff from. If omitted the parent revision of the until revision is used

srcPath

string

the source path for the file, if it was copied, moved or renamed

whitespace

string

optional whitespace flag which can be set to ignore-all

withComments

boolean

Default: true

true to embed comments in the diff (the default); otherwise false to stream the diff without comments

Example response representations:

  • 200 - application/json (diff) [expand]

    Example
    {"diffs":[{"source":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"destination":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"hunks":[{"sourceLine":1,"sourceSpan":1,"destinationLine":1,"destinationSpan":2,"segments":[{"type":"REMOVED","lines":[{"destination":1,"source":1,"line":"import sys","truncated":false}],"truncated":false},{"type":"ADDED","lines":[{"destination":1,"source":2,"line":"import re","truncated":false},{"destination":2,"source":3,"line":"import os","truncated":false}],"truncated":false}],"truncated":false}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}

    A diff between two revisions.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The until parameter was not supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/diff/{path:.*}

resource-wide template parameters
parametervaluedescription

commitId

string

until ID, as indicated by the path

path

string

the path to the file which should be diffed (optional)

commitId

string

until ID, as indicated by the path

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/diff/{path:.*}?autoSrcPath&contextLines&since&srcPath&whitespace

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Stream the diff between two provided revisions.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

autoSrcPath

boolean

Default: false

true to automatically try to find the source path when it's not provided, false otherwise. Requires the path to be provided.

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

since

string

the base revision to diff from. If omitted the parent revision of the until revision is used

srcPath

string

the source path for the file, if it was copied, moved or renamed

whitespace

string

optional whitespace flag which can be set to ignore-all

Example response representations:

  • 200 - text/plain [expand]

    A raw diff between two revisions.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The until parameter was not supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/diff/{path:.*}?autoSrcPath&contextLines&since&srcPath&whitespace&withComments&avatarSize&avatarScheme

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the diff between two provided revisions.

Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more truncated flags will be set to true on the "segments", "hunks" and "diffs" properties, as well as the top-level object, in the returned JSON response.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

autoSrcPath

boolean

Default: false

true to automatically try to find the source path when it's not provided, false otherwise. Requires the path to be provided.

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

since

string

the base revision to diff from. If omitted the parent revision of the until revision is used

srcPath

string

the source path for the file, if it was copied, moved or renamed

whitespace

string

optional whitespace flag which can be set to ignore-all

withComments

boolean

Default: true

true to embed comments in the diff (the default); otherwise false to stream the diff without comments

avatarSize

string

if present the service adds avatar URLs for comment authors where the provided value specifies the desired avatar size in pixels

avatarScheme

string

the security scheme for avatar URLs. If the scheme is not present then it is inherited from the request. It can be set to "https" to force the use of secure URLs

Example response representations:

  • 200 - application/json (diff) [expand]

    Example
    {"diffs":[{"source":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"destination":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"hunks":[{"sourceLine":1,"sourceSpan":1,"destinationLine":1,"destinationSpan":2,"segments":[{"type":"REMOVED","lines":[{"destination":1,"source":1,"line":"import sys","truncated":false}],"truncated":false},{"type":"ADDED","lines":[{"destination":1,"source":2,"line":"import re","truncated":false},{"destination":2,"source":3,"line":"import os","truncated":false}],"truncated":false}],"truncated":false}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}

    A diff between two revisions.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The until parameter was not supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/pull-requests

resource-wide template parameters
parametervaluedescription

commitId

string

the commit ID

Methods

GET

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of pull requests in the current repository that contain the given commit.

The user must be authenticated and have access to the specified repository to call this resource.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"id":101,"version":1,"title":"Talking Nerdy","description":"It’s a kludge, but put the tuple from the database in the cache.","state":"OPEN","open":true,"closed":false,"createdDate":1359075920,"updatedDate":1359085920,"fromRef":{"id":"refs/heads/feature-ABC-123","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"toRef":{"id":"refs/heads/master","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"locked":false,"author":{"user":{"name":"tom","emailAddress":"tom@example.com","id":115026,"displayName":"Tom","active":true,"slug":"tom","type":"NORMAL"},"role":"AUTHOR","approved":true,"status":"APPROVED"},"reviewers":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":true,"status":"APPROVED"}],"participants":[{"user":{"name":"harry","emailAddress":"harry@example.com","id":99049120,"displayName":"Harry","active":true,"slug":"harry","type":"NORMAL"},"role":"PARTICIPANT","approved":true,"status":"APPROVED"},{"user":{"name":"dick","emailAddress":"dick@example.com","id":3083181,"displayName":"Dick","active":true,"slug":"dick","type":"NORMAL"},"role":"PARTICIPANT","approved":false,"status":"UNAPPROVED"}],"links":{"self":[{"href":"http://link/to/pullrequest"}]}}],"start":0}

    Return a page of pull requests in the current repository containing the given commit.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to see the request repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The request repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{commitId}/watch

resource-wide template parameters
parametervaluedescription

commitId

string

the full {@link Commit#getId() ID} of the commit within the repository

Methods

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Remove the authenticated user as a watcher for the specified commit.

The authenticated user must have REPO_READ permission for the repository containing the commit to call this resource.

Example response representations:

  • 204 [expand]

    The user is no longer watching the commit.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project, repository or commit does not exist.

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Add the authenticated user as a watcher for the specified commit.

The authenticated user must have REPO_READ permission for the repository containing the commit to call this resource.

Example response representations:

  • 204 [expand]

    The user is now watching the commit.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project, repository or commit does not exist.

Compare two commits or refs. <p> Each commit can be specified using either a commit ID, a qualified ref name or a unqualified ref name (the latter should be non-ambiguous).

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/compare/changes

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/compare/changes?from&to&fromRepo

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Gets the file changes available in the from commit but not in the to commit.

If either the from or to commit are not specified, they will be replaced by the default branch of their containing repository.

request query parameters
parametervaluedescription

from

string

the source commit (can be a partial/full commit ID or qualified/unqualified ref name)

to

string

the target commit (can be a partial/full commit ID or qualified/unqualified ref name)

fromRepo

string

Default:

an optional parameter specifying the source repository containing the source commit if that commit is not present in the current repository; the repository can be specified by either its ID fromRepo=42 or by its project key plus its repo slug separated by a slash: fromRepo=projectKey/repoSlug

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"contentId":"abcdef0123abcdef4567abcdef8987abcdef6543","fromContentId":"bcdef0123abcdef4567abcdef8987abcdef6543a","path":{"components":["new","path","to","file.txt"],"parent":"new/path/to","name":"file.txt","extension":"txt","toString":"new/path/to/file.txt"},"executable":false,"percentUnchanged":98,"type":"MOVE","nodeType":"FILE","srcPath":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"srcExecutable":false,"links":{"self":[{"href":"http://link/to/restchange"}]}}],"start":0}

    A page of changes.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The source or target commit does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/compare/diff{path:.*}

resource-wide template parameters
parametervaluedescription

path

string

the path to the file to diff (optional)

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/compare/diff{path:.*}?from&to&fromRepo&srcPath&contextLines&whitespace

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Gets a diff of the changes available in the from commit but not in the to commit.

If either the from or to commit are not specified, they will be replaced by the default branch of their containing repository.

request query parameters
parametervaluedescription

from

string

the source commit (can be a partial/full commit ID or qualified/unqualified ref name)

to

string

the target commit (can be a partial/full commit ID or qualified/unqualified ref name)

fromRepo

string

Default:

an optional parameter specifying the source repository containing the source commit if that commit is not present in the current repository; the repository can be specified by either its ID fromRepo=42 or by its project key plus its repo slug separated by a slash: fromRepo=projectKey/repoSlug

srcPath

string

source path

contextLines

int

Default: -1

an optional number of context lines to include around each added or removed lines in the diff

whitespace

string

an optional whitespace flag which can be set to ignore-all

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"diffs":[{"source":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"destination":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"hunks":[{"sourceLine":1,"sourceSpan":1,"destinationLine":1,"destinationSpan":2,"segments":[{"type":"REMOVED","lines":[{"destination":1,"source":1,"line":"import sys","truncated":false}],"truncated":false},{"type":"ADDED","lines":[{"destination":1,"source":2,"line":"import re","truncated":false},{"destination":2,"source":3,"line":"import os","truncated":false}],"truncated":false}],"truncated":false}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}

    The diff of the changes.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The source or target commit does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/compare/commits

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/compare/commits?from&to&fromRepo

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Gets the commits accessible from the from commit but not in the to commit.

If either the from or to commit are not specified, they will be replaced by the default branch of their containing repository.

request query parameters
parametervaluedescription

from

string

the source commit (can be a partial/full commit ID or qualified/unqualified ref name)

to

string

the target commit (can be a partial/full commit ID or qualified/unqualified ref name)

fromRepo

string

Default:

an optional parameter specifying the source repository containing the source commit if that commit is not present in the current repository; the repository can be specified by either its ID fromRepo=42 or by its project key plus its repo slug separated by a slash: fromRepo=projectKey/repoSlug

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"id":"def0123abcdef4567abcdef8987abcdef6543abc","displayId":"def0123abcd","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"More work on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]}],"start":0,"authorCount":1,"totalCount":1}

    A page of commits.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The source or target commit does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/diff

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/diff?contextLines&since&srcPath&until&whitespace

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Stream the raw diff between two provided revisions.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

since

string

the base revision to diff from. If omitted the parent revision of the until revision is used

srcPath

string

the source path for the file, if it was copied, moved or renamed

until

string

the target revision to diff to (required)

whitespace

string

optional whitespace flag which can be set to ignore-all

Example response representations:

  • 200 - text/plain [expand]

    A raw diff between two revisions.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The until parameter was not supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/diff?contextLines&since&srcPath&until&whitespace

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the diff for a specified file path between two provided revisions.

Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more truncated flags will be set to true on the segments, hunks and diffs substructures in the returned JSON response.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

since

string

the base revision to diff from. If omitted the parent revision of the until revision is used

srcPath

string

the source path for the file, if it was copied, moved or renamed

until

string

the target revision to diff to (required)

whitespace

string

optional whitespace flag which can be set to ignore-all

Example response representations:

  • 200 - application/json (diff) [expand]

    Example
    {"diffs":[{"source":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"destination":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"hunks":[{"sourceLine":1,"sourceSpan":1,"destinationLine":1,"destinationSpan":2,"segments":[{"type":"REMOVED","lines":[{"destination":1,"source":1,"line":"import sys","truncated":false}],"truncated":false},{"type":"ADDED","lines":[{"destination":1,"source":2,"line":"import re","truncated":false},{"destination":2,"source":3,"line":"import os","truncated":false}],"truncated":false}],"truncated":false}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}

    A diff of a file path.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The path or until parameters were not supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/diff/{path:.*}

resource-wide template parameters
parametervaluedescription

path

string

the path to the file which should be diffed (required)

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/diff/{path:.*}?contextLines&since&srcPath&until&whitespace

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Stream the raw diff between two provided revisions.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

since

string

the base revision to diff from. If omitted the parent revision of the until revision is used

srcPath

string

the source path for the file, if it was copied, moved or renamed

until

string

the target revision to diff to (required)

whitespace

string

optional whitespace flag which can be set to ignore-all

Example response representations:

  • 200 - text/plain [expand]

    A raw diff between two revisions.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The until parameter was not supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/diff/{path:.*}?contextLines&since&srcPath&until&whitespace

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the diff for a specified file path between two provided revisions.

Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more truncated flags will be set to true on the segments, hunks and diffs substructures in the returned JSON response.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

since

string

the base revision to diff from. If omitted the parent revision of the until revision is used

srcPath

string

the source path for the file, if it was copied, moved or renamed

until

string

the target revision to diff to (required)

whitespace

string

optional whitespace flag which can be set to ignore-all

Example response representations:

  • 200 - application/json (diff) [expand]

    Example
    {"diffs":[{"source":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"destination":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"hunks":[{"sourceLine":1,"sourceSpan":1,"destinationLine":1,"destinationSpan":2,"segments":[{"type":"REMOVED","lines":[{"destination":1,"source":1,"line":"import sys","truncated":false}],"truncated":false},{"type":"ADDED","lines":[{"destination":1,"source":2,"line":"import re","truncated":false},{"destination":2,"source":3,"line":"import os","truncated":false}],"truncated":false}],"truncated":false}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}

    A diff of a file path.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The path or until parameters were not supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/files

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/files?at

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of files from particular directory of a repository. The search is done recursively, so all files from any sub-directory of the specified directory will be returned.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

at

string

the commit ID or ref (e.g. a branch or tag) to list the files at. If not specified the default branch will be used instead.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":["path/to/file.txt"],"start":0}

    A page of files.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The path requested is not a directory at the supplied commit.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The path requested does not exist at the supplied commit.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/files/{path:.*}

resource-wide template parameters
parametervaluedescription

path

string

Default:

the directory to list files for.

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/files/{path:.*}?at

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of files from particular directory of a repository. The search is done recursively, so all files from any sub-directory of the specified directory will be returned.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

at

string

the commit ID or ref (e.g. a branch or tag) to list the files at. If not specified the default branch will be used instead.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":["path/to/file.txt"],"start":0}

    A page of files.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The path requested is not a directory at the supplied commit.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The path requested does not exist at the supplied commit.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/labels

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Get all labels applied to the given repository.

The authenticated user must have REPO_READ permission for the specified repository.

Example response representations:

  • 200 - application/json (label) [expand]

    Example
    {"name":"labelName"}

    The applied label.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the labels.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Applies a label to the repository.

The authenticated user must have REPO_ADMIN permission for the specified repository.

Example request representations:

  • application/json [expand]

    Example
    {"name":"labelName"}

Example response representations:

  • 200 - application/json (label) [expand]

    Example
    {"name":"labelName"}

    The applied label.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    A validation error prevented the label from being created or applied. Possible validation errors include: The name of the label contains uppercase characters, the name is smaller than 3 characters or longer than 50 characters, the label contains other characters than a-z 0-9 and - or the label is already applied to the given 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 apply a label.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/labels/{labelName}

resource-wide template parameters
parametervaluedescription

labelName

string

the label to remove

Methods

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Remove label that is applied to the given repository.

The authenticated user must have REPO_ADMIN permission for the specified repository.

Example response representations:

  • 204 - application/json [expand]

    An empty response indicating that the label is no longer associated to 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 remove the label.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/last-modified

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/last-modified?at

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Streams files in the requested path with the last commit to modify each file. Commit modifications are traversed starting from the at commit or, if not specified, from the tip of the default branch.

Unless the repository is public, the authenticated user must have REPO_READ access to call this resource.

request query parameters
parametervaluedescription

at

string

the commit to use as the starting point when listing files and calculating modifications

Example response representations:

  • 200 - application/json (modifications) [expand]

    Example
    {"files":{"pom.xml":{"id":"def0123abcdef4567abcdef8987abcdef6543abc","displayId":"def0123abcd","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"More work on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]},"README.md":{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0123a","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"WIP on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]}},"latestCommit":{"id":"def0123abcdef4567abcdef8987abcdef6543abc","displayId":"def0123abcd","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"More work on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]}}

    A map of files to the last commit that modified them, and the latest commit to update the requested path.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    No at commit was specified. When streaming modifications, an explicit starting commit must be supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist or does not contain the at commit, or the at commit does not contain the requested path.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/last-modified/{path:.*}

resource-wide template parameters
parametervaluedescription

path

string

the path within the repository whose files should be streamed

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/last-modified/{path:.*}?at

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Streams files in the requested path with the last commit to modify each file. Commit modifications are traversed starting from the at commit or, if not specified, from the tip of the default branch.

Unless the repository is public, the authenticated user must have REPO_READ access to call this resource.

request query parameters
parametervaluedescription

at

string

the commit to use as the starting point when listing files and calculating modifications

Example response representations:

  • 200 - application/json (modifications) [expand]

    Example
    {"files":{"pom.xml":{"id":"def0123abcdef4567abcdef8987abcdef6543abc","displayId":"def0123abcd","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"More work on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]},"README.md":{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0123a","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"WIP on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]}},"latestCommit":{"id":"def0123abcdef4567abcdef8987abcdef6543abc","displayId":"def0123abcd","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"More work on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]}}

    A map of files to the last commit that modified them, and the latest commit to update the requested path.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    No at commit was specified. When streaming modifications, an explicit starting commit must be supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist or does not contain the at commit, or the at commit does not contain the requested path.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/participants

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/participants?direction&filter&role

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of participant users for all the pull requests to or from the specified repository.

Optionally clients can specify following filters.

request query parameters
parametervaluedescription

direction

string

Default: incoming

(optional, defaults to INCOMING) the direction relative to the specified repository. Either INCOMING or OUTGOING.

filter

string

(optional) return only users, whose username, name or email address contain the filter value

role

string

(optional) The role associated with the pull request participant. This must be one of AUTHOR, REVIEWER, orPARTICIPANT

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"name":"charlie","emailAddress":"charlie@example.com"}

    A page of users that match the search criteria.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the specified repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/patch

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/patch?allAncestors&since&until

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the patch content for a repository at a specified revision.

Cache headers are added to the response (only if full commit hashes are used, not in the case of short hashes).

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

allAncestors

boolean

indicates whether or not to generate a patch which includes all the ancestors of the until revision. If true, the value provided by since is ignored.

since

string

the base revision from which to generate the patch. This is only applicable when allAncestors is false. If omitted the patch will represent one single commit, the until.

until

string

the target revision from which to generate the patch (required)

Example response representations:

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups?filter

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of groups that have been granted at least one permission for the specified repository.

The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.

request query parameters
parametervaluedescription

filter

string

if specified only group names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"group":{"name":"group_a"},"permission":"ADMIN"}],"start":0}

    A page of groups and their highest permissions for the specified repository.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not a repository administrator for the specified repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

DELETE

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups?name

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Revoke all permissions for the specified repository for a group.

The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.

In addition, a user may not revoke a group's permissions if it will reduce their own permission level.

request query parameters
parametervaluedescription

name

string

the name of the group

Example response representations:

  • 204 [expand]

    All repository permissions were revoked from the group for the specified repository.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator of the specified repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or group does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would reduce the currently authenticated user's permission level.

PUT

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups?permission&name

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Promote or demote a group's permission level for the specified repository. Available repository permissions are:

  • REPO_READ
  • REPO_WRITE
  • REPO_ADMIN
See the Bitbucket Server documentation for a detailed explanation of what each permission entails.

The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource. In addition, a user may not demote a group's permission level if their own permission level would be reduced as a result.

request query parameters
parametervaluedescription

permission

string

the permission to grant

name

string

the names of the groups

Example response representations:

  • 204 [expand]

    The requested permission was granted.

  • 400 - application/json (errors) [expand]

    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 was malformed or the specified permission does not exist.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator for the specified repository.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would reduce the currently authenticated user's permission level.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or group does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups/none

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups/none?filter

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of groups that have no granted permissions for the specified repository.

The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.

request query parameters
parametervaluedescription

filter

string

if specified only group names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"group-a","deletable":true}],"start":0}

    A page of groups that have not been granted any permissions for the specified repository.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not a repository administrator for the specified repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users?filter

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of users that have been granted at least one permission for the specified repository.

The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.

request query parameters
parametervaluedescription

filter

string

if specified only user names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"permission":"ADMIN"}],"start":0}

    A page of users and their highest permissions for the specified repository.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not a repository administrator for the specified repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

DELETE

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users?name

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Revoke all permissions for the specified repository for a user.

The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.

In addition, a user may not revoke their own repository permissions if they do not have a higher project or global permission.

request query parameters
parametervaluedescription

name

string

the name of the user

Example response representations:

  • 204 [expand]

    All repository permissions were revoked from the user for the specified repository.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator of the specified repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or group does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would reduce the currently authenticated user's permission level.

PUT

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users?name&permission

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Promote or demote a user's permission level for the specified repository. Available repository permissions are:

  • REPO_READ
  • REPO_WRITE
  • REPO_ADMIN
See the Bitbucket Server documentation for a detailed explanation of what each permission entails.

The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource. In addition, a user may not reduce their own permission level unless they have a project or global permission that already implies that permission.

request query parameters
parametervaluedescription

name

string

the names of the users

permission

string

the permission to grant

Example response representations:

  • 204 [expand]

    The requested permission was granted.

  • 400 - application/json (errors) [expand]

    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 was malformed or the specified permission does not exist.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not an administrator for the specified repository.

  • 403 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The action was disallowed as it would reduce the currently authenticated user's permission level.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or user does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users/none

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users/none?filter

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of licensed users that have no granted permissions for the specified repository.

The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or global permission to call this resource.

request query parameters
parametervaluedescription

filter

string

if specified only user names containing the supplied string will be returned

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"group-a","deletable":true}],"start":0}

    A page of users that have not been granted any permissions for the specified repository.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not a repository administrator for the specified repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests?direction&at&state&order&withAttributes&withProperties&filterText

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of pull requests to or from the specified repository.

The authenticated user must have REPO_READ permission for the specified repository to call this resource. Optionally clients can specify PR participant filters. Each filter has a mandatory username.N parameter, and the optional role.N and approved.N parameters.

  • username.N - the "root" of a single participant filter, where "N" is a natural number starting from 1. This allows clients to specify multiple participant filters, by providing consecutive filters as username.1, username.2 etc. Note that the filters numbering has to start with 1 and be continuous for all filters to be processed. The total allowed number of participant filters is 10 and all filters exceeding that limit will be dropped.
  • role.N(optional) the role associated with username.N. This must be one of AUTHOR, REVIEWER, orPARTICIPANT
  • approved.N(optional) the approved status associated with username.N. That is whether username.N has approved the PR. Either true, or false

request query parameters
parametervaluedescription

direction

string

Default: incoming

(optional, defaults to INCOMING) the direction relative to the specified repository. Either INCOMING or OUTGOING.

at

string

(optional) a fully-qualified branch ID to find pull requests to or from, such as refs/heads/master

state

string

(optional, defaults to OPEN). Supply ALL to return pull request in any state. If a state is supplied only pull requests in the specified state will be returned. Either OPEN, DECLINED or MERGED.

order

string

(optional, defaults to NEWEST) the order to return pull requests in, either OLDEST (as in: "oldest first") or NEWEST.

withAttributes

boolean

Default: true

(optional) defaults to true, whether to return additional pull request attributes

withProperties

boolean

Default: true

(optional) defaults to true, whether to return additional pull request properties

filterText

string

(optional) If specified, only pull requests where the title or description contains the supplied string will be returned.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"id":101,"version":1,"title":"Talking Nerdy","description":"It’s a kludge, but put the tuple from the database in the cache.","state":"OPEN","open":true,"closed":false,"createdDate":1359075920,"updatedDate":1359085920,"fromRef":{"id":"refs/heads/feature-ABC-123","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"toRef":{"id":"refs/heads/master","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"locked":false,"author":{"user":{"name":"tom","emailAddress":"tom@example.com","id":115026,"displayName":"Tom","active":true,"slug":"tom","type":"NORMAL"},"role":"AUTHOR","approved":true,"status":"APPROVED"},"reviewers":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":true,"status":"APPROVED"}],"participants":[{"user":{"name":"harry","emailAddress":"harry@example.com","id":99049120,"displayName":"Harry","active":true,"slug":"harry","type":"NORMAL"},"role":"PARTICIPANT","approved":true,"status":"APPROVED"},{"user":{"name":"dick","emailAddress":"dick@example.com","id":3083181,"displayName":"Dick","active":true,"slug":"dick","type":"NORMAL"},"role":"PARTICIPANT","approved":false,"status":"UNAPPROVED"}],"links":{"self":[{"href":"http://link/to/pullrequest"}]}}],"start":0}

    A page of pull requests that match the search criteria.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the specified pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Create a new pull request from a source branch or tag to a target branch. The source and target may be in the same repository, or different ones. (Note that different repositories must belong to the same {@link Repository#getHierarchyId() hierarchy}.)

The fromRef may be a branch or a tag. The toRef is required to be a branch. Tags are not allowed as targets because tags are intended to be immutable and should not be changed after they are created.

The authenticated user must have REPO_READ permission for the fromRef and toRef repositories to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"title":"Talking Nerdy","description":"It’s a kludge, but put the tuple from the database in the cache.","state":"OPEN","open":true,"closed":false,"fromRef":{"id":"refs/heads/feature-ABC-123","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"toRef":{"id":"refs/heads/master","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"locked":false,"reviewers":[{"user":{"name":"charlie"}}]}

Example response representations:

  • 201 - application/json (pullRequest) [expand]

    Example
    {"id":101,"version":1,"title":"Talking Nerdy","description":"It’s a kludge, but put the tuple from the database in the cache.","state":"OPEN","open":true,"closed":false,"createdDate":1359075920,"updatedDate":1359075920,"fromRef":{"id":"refs/heads/feature-ABC-123","displayId":"feature-ABC-123","latestCommit":"babecafebabecafebabecafebabecafebabecafe","type":"BRANCH","repository":{"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}}},"toRef":{"id":"refs/heads/master","displayId":"master","latestCommit":"cafebabecafebabecafebabecafebabecafebabe","type":"BRANCH","repository":{"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}}},"locked":false,"author":{"user":{"name":"alice","emailAddress":"alice@example.com","id":92903040,"displayName":"Alice","active":true,"slug":"alice","type":"NORMAL"},"role":"PARTICIPANT","approved":false,"status":"UNAPPROVED"},"reviewers":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":false,"status":"UNAPPROVED"}],"participants":[],"links":{"self":[{"href":"http://link/to/pullrequest"}]}}

    The newly created pull request.

  • 400 - application/json (errors) [expand]

    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 pull request entity supplied in the request was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to create a pull request between the two specified repositories.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    One of the specified repositories or branches does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    One of the following error cases occurred (check the error message for more details):

    • There was a problem resolving one or more reviewers.
    • The specified branches were the same.
    • The to branch is already up-to-date with all the commits on the from branch.
    • A pull request between the two branches already exists.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}

resource-wide template parameters
parametervaluedescription

pullRequestId

long

the ID of the pull request within the repository

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example response representations:

  • 200 - application/json (pullRequest) [expand]

    Example
    {"id":101,"version":1,"title":"Talking Nerdy","description":"It’s a kludge, but put the tuple from the database in the cache.","state":"OPEN","open":true,"closed":false,"createdDate":1359075920,"updatedDate":1359085920,"fromRef":{"id":"refs/heads/feature-ABC-123","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"toRef":{"id":"refs/heads/master","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"locked":false,"author":{"user":{"name":"tom","emailAddress":"tom@example.com","id":115026,"displayName":"Tom","active":true,"slug":"tom","type":"NORMAL"},"role":"AUTHOR","approved":true,"status":"APPROVED"},"reviewers":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":true,"status":"APPROVED"}],"participants":[{"user":{"name":"harry","emailAddress":"harry@example.com","id":99049120,"displayName":"Harry","active":true,"slug":"harry","type":"NORMAL"},"role":"PARTICIPANT","approved":true,"status":"APPROVED"},{"user":{"name":"dick","emailAddress":"dick@example.com","id":3083181,"displayName":"Dick","active":true,"slug":"dick","type":"NORMAL"},"role":"PARTICIPANT","approved":false,"status":"UNAPPROVED"}],"links":{"self":[{"href":"http://link/to/pullrequest"}]}}

    The specified pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the specified pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Update the title, description, reviewers or destination branch of an existing pull request.

Note: the reviewers list may be updated using this resource. However the author and participants list may not.

The authenticated user must either:

  • be the author of the pull request and have the REPO_READ permission for the repository that this pull request targets; or
  • have the REPO_WRITE permission for the repository that this pull request targets
to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"id":101,"version":2,"title":"Talking Nerdy","description":"It’s a hack, but force AO to eagerly initialize to avoid deadlocks.","reviewers":[{"user":{"name":"charlie"}}]}

Example response representations:

  • 200 - application/json (pullRequest) [expand]

    Example
    {"id":101,"version":1,"title":"Talking Nerdy","description":"It’s a kludge, but put the tuple from the database in the cache.","state":"OPEN","open":true,"closed":false,"createdDate":1359075920,"updatedDate":1359085920,"fromRef":{"id":"refs/heads/feature-ABC-123","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"toRef":{"id":"refs/heads/master","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"locked":false,"author":{"user":{"name":"tom","emailAddress":"tom@example.com","id":115026,"displayName":"Tom","active":true,"slug":"tom","type":"NORMAL"},"role":"AUTHOR","approved":true,"status":"APPROVED"},"reviewers":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":true,"status":"APPROVED"}],"participants":[{"user":{"name":"harry","emailAddress":"harry@example.com","id":99049120,"displayName":"Harry","active":true,"slug":"harry","type":"NORMAL"},"role":"PARTICIPANT","approved":true,"status":"APPROVED"},{"user":{"name":"dick","emailAddress":"dick@example.com","id":3083181,"displayName":"Dick","active":true,"slug":"dick","type":"NORMAL"},"role":"PARTICIPANT","approved":false,"status":"UNAPPROVED"}],"links":{"self":[{"href":"http://link/to/pullrequest"}]}}

    The updated pull request.

  • 400 - application/json (errors) [expand]

    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}]}

    One of the following error cases occurred (check the error message for more details):

    • The request tried to modify the author or participants.
    • The pull request's version attribute was not specified.
    • A reviewer's username was not specified.
    • The toRef ID value was incorrectly left blank

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update the specified pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    One of the specified repositories or branches does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    One of the following error cases occurred (check the error message for more details):

    • The specified version is out of date.
    • One of the reviewers could not be added to the pull request.
    • If updating the destination branch:
      • There is already an open pull request with an identical to branch
      • The from and new to branch are the same
      • The new destination branch up-to-date is up-to-date with all of changes from the from branch, resulting in a pull request with nothing to merge

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Deletes a pull request.

To call this resource, users must be authenticated and have permission to view the pull request. Additionally, they must:

  • be the pull request author, if the system is configured to allow authors to delete their own pull requests (this is the default) OR
  • have repository administrator permission for the repository the pull request is targeting
A body containing the version of the pull request must be provided with this request.
{ "version": 1 }

Example request representations:

  • application/json [expand]

    Example
    {"version":1}

Example response representations:

  • 204 - application/json [expand]
  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the specified pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}.diff

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}.diff?contextLines&whitespace

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Streams the raw diff for a pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

whitespace

string

optional whitespace flag which can be set to ignore-all

Example response representations:

  • 200 - text/plain [expand]

    A raw diff for the specified pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the specified pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the pull request does not exist

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}.patch

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Streams a patch representing a pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example response representations:

  • 200 - text/plain [expand]

    A patch representing the specified pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the current user cannot access the pull request

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the pull request does not exist

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/activities

resource-wide template parameters
parametervaluedescription

pullRequestId

long

the ID of the pull request within the repository

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/activities?fromId&fromType

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of activity associated with a pull request.

Activity items include comments, approvals, rescopes (i.e. adding and removing of commits), merges and more.

Different types of activity items may be introduced in newer versions of Stash or by user installed plugins, so clients should be flexible enough to handle unexpected entity shapes in the returned page.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

fromId

long

(optional) the ID of the activity item to use as the first item in the returned page

fromType

string

(required if fromId is present) the type of the activity item specified by fromId (either COMMENT or ACTIVITY)

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":3,"limit":25,"isLastPage":true,"values":[{"id":101,"createdDate":1359065920,"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"action":"COMMENTED","commentAction":"ADDED","comment":{"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}},"commentAnchor":{"line":1,"lineType":"CONTEXT","fileType":"FROM","path":"path/to/file","srcPath":"path/to/file"}},{"id":101,"createdDate":1359065920,"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"action":"RESCOPED","fromHash":"abcdeabcdeabcdeabcdeabcdeabcdeabcdeabcde","previousFromHash":"bcdeabcdeabcdeabcdeabcdeabcdeabcdeabcdea","previousToHash":"cdeabcdeabcdeabcdeabcdeabcdeabcdeabcdeab","toHash":"ddeabcdeabcdeabcdeabcdeabcdeabcdeabcdeabc","added":{"commits":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0123a","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"WIP on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]}],"total":1},"removed":{"commits":[{"id":"def0123abcdef4567abcdef8987abcdef6543abc","displayId":"def0123abcd","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"More work on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]}],"total":1}},{"id":101,"createdDate":1359085920,"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"action":"MERGED"}],"start":0}

    A page of activity relating to the specified pull request.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the specified pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/decline

resource-wide template parameters
parametervaluedescription

pullRequestId

long

the pullrequest ID provided by the path

Methods

POST

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/decline?version

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Decline a pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

version

int

Default: -1

the current version of the pull request. If the server's version isn't the same as the specified version the operation will fail. To determine the current version of the pull request it should be fetched from the server prior to this operation. Look for the 'version' attribute in the returned JSON structure.

Example response representations:

  • 200 [expand]

    The pull request was declined.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The pull request is not OPEN or has been updated since the version specified by the request.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/merge

resource-wide template parameters
parametervaluedescription

pullRequestId

long

the ID of the pull request within the repository

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Test whether a pull request can be merged.

A pull request may not be merged if:

  • there are conflicts that need to be manually resolved before merging; and/or
  • one or more merge checks have vetoed the merge.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example response representations:

  • 200 - application/json (pullRequest) [expand]

    Example
    {"canMerge":false,"conflicted":true,"outcome":"CONFLICTED","vetoes":[{"summaryMessage":"You may not merge after 6pm on a Friday.","detailedMessage":"It is likely that your Blood Alcohol Content (BAC) exceeds the threshold for making sensible decisions regarding pull requests. Please try again on Monday."}]}

    The mergeability status of the pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the specified pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified pull request is not open.

POST

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/merge?version

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Merge the specified pull request.

The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

version

int

Default: -1

the current version of the pull request. If the server's version isn't the same as the specified version the operation will fail. To determine the current version of the pull request it should be fetched from the server prior to this operation. Look for the 'version' attribute in the returned JSON structure.

Example response representations:

  • 200 - application/json (pullRequest) [expand]

    Example
    {"id":101,"version":1,"title":"Talking Nerdy","description":"It’s a kludge, but put the tuple from the database in the cache.","state":"MERGED","open":false,"closed":true,"createdDate":1359075920,"updatedDate":1359115920,"closedDate":1359115920,"fromRef":{"id":"refs/heads/feature-ABC-123","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"toRef":{"id":"refs/heads/master","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"locked":false,"author":{"user":{"name":"tom","emailAddress":"tom@example.com","id":115026,"displayName":"Tom","active":true,"slug":"tom","type":"NORMAL"},"role":"AUTHOR","approved":true,"status":"APPROVED"},"reviewers":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":true,"status":"APPROVED"}],"participants":[{"user":{"name":"harry","emailAddress":"harry@example.com","id":99049120,"displayName":"Harry","active":true,"slug":"harry","type":"NORMAL"},"role":"PARTICIPANT","approved":true,"status":"APPROVED"},{"user":{"name":"dick","emailAddress":"dick@example.com","id":3083181,"displayName":"Dick","active":true,"slug":"dick","type":"NORMAL"},"role":"PARTICIPANT","approved":true,"status":"APPROVED"}],"properties":{"commentCount":3},"links":{"self":[{"href":"http://link/to/pullrequest"}]}}

    The merged pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to merge the specified pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    One of the following error cases occurred (check the error message for more details):

    • The pull request has conflicts.
    • A merge check vetoed the merge.
    • The specified version is out of date.
    • The specified pull request is not open.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/reopen

resource-wide template parameters
parametervaluedescription

pullRequestId

long

the ID of the pull request within the repository

Methods

POST

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/reopen?version

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Re-open a declined pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

version

int

Default: -1

the current version of the pull request. If the server's version isn't the same as the specified version the operation will fail. To determine the current version of the pull request it should be fetched from the server prior to this operation. Look for the 'version' attribute in the returned JSON structure.

Example response representations:

  • 200 - application/json (pullRequest) [expand]

    Example
    {"id":101,"version":1,"title":"Talking Nerdy","description":"It’s a kludge, but put the tuple from the database in the cache.","state":"OPEN","open":true,"closed":false,"createdDate":1359075920,"updatedDate":1359085920,"fromRef":{"id":"refs/heads/feature-ABC-123","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"toRef":{"id":"refs/heads/master","repository":{"slug":"my-repo","name":null,"project":{"key":"PRJ"}}},"locked":false,"author":{"user":{"name":"tom","emailAddress":"tom@example.com","id":115026,"displayName":"Tom","active":true,"slug":"tom","type":"NORMAL"},"role":"AUTHOR","approved":true,"status":"APPROVED"},"reviewers":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":true,"status":"APPROVED"}],"participants":[{"user":{"name":"harry","emailAddress":"harry@example.com","id":99049120,"displayName":"Harry","active":true,"slug":"harry","type":"NORMAL"},"role":"PARTICIPANT","approved":true,"status":"APPROVED"},{"user":{"name":"dick","emailAddress":"dick@example.com","id":3083181,"displayName":"Dick","active":true,"slug":"dick","type":"NORMAL"},"role":"PARTICIPANT","approved":false,"status":"UNAPPROVED"}],"links":{"self":[{"href":"http://link/to/pullrequest"}]}}

    The merged pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to reopen the specified pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    One of the following error cases occurred (check the error message for more details):

    • The pull request is not in a declined state.
    • The specified version is out of date.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/approve

resource-wide template parameters
parametervaluedescription

pullRequestId

long

the ID of the pull request within the repository

Methods

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Remove approval from a pull request as the current user. This does not remove the user as a participant.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Deprecated since 4.2. Use /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug} instead

Example response representations:

  • 201 - application/json (participant) [expand]

    Example
    {"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":false,"status":"UNAPPROVED"}

    Details of the updated participant

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist or the current user is not a participant on the pull request.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The pull request is not open.

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Approve a pull request as the current user. Implicitly adds the user as a participant if they are not already.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Deprecated since 4.2. Use /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug} instead

Example response representations:

  • 201 - application/json (participant) [expand]

    Example
    {"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":true,"status":"APPROVED"}

    Details of the new participant

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The pull request is not open.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/blocker-comments

Resource for managing BLOCKER comments on pull requests.

Methods

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Add a new blocker comment.

Comments can be added in a few places by setting different attributes:

General pull request blocker comment:

     {
         "text": "A task on a pull request."
     }
     
Blocker reply to a comment:
     {
         "text": "This reply is a task.",
         "parent": {
             "id": 1
         }
     }
     
General blocker file comment:
     {
         "text": "A blocker comment on a file.",
         "anchor": {
             "diffType": "RANGE",
             "fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd",
             "path": "path/to/file",
             "srcPath": "path/to/file",
             "toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b"
         }
     }
     
Blocker file line comment:
     {
         "text": "A task on a particular line within a file.",
         "anchor": {
             "diffType": "COMMIT",
             "line": 1,
             "lineType": "CONTEXT",
             "fileType": "FROM",
             "fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd",
             "path": "path/to/file",
             "srcPath": "path/to/file",
             "toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b"
         }
     }
     

For file and line comments, 'path' refers to the path of the file to which the comment should be applied and 'srcPath' refers to the path the that file used to have (only required for copies and moves). Also, fromHash and toHash refer to the sinceId / untilId (respectively) used to produce the diff on which the comment was added. Finally diffType refers to the type of diff the comment was added on. For backwards compatibility purposes if no diffType is provided and no fromHash/toHash pair is provided the diffType will be resolved to 'EFFECTIVE'. In any other cases the diffType is REQUIRED.

For line comments, 'line' refers to the line in the diff that the comment should apply to. 'lineType' refers to the type of diff hunk, which can be:

  • 'ADDED' - for an added line;
  • 'REMOVED' - for a removed line; or
  • 'CONTEXT' - for a line that was unmodified but is in the vicinity of the diff.
'fileType' refers to the file of the diff to which the anchor should be attached - which is of relevance when displaying the diff in a side-by-side way. Currently the supported values are:
  • 'FROM' - the source file of the diff
  • 'TO' - the destination file of the diff
If the current user is not a participant the user is added as a watcher of the pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"text":"An insightful comment.","parent":{"id":1,"severity":"NORMAL","state":"OPEN"},"anchor":{"line":1,"lineType":"CONTEXT","fileType":"FROM","path":"path/to/file","srcPath":"path/to/file"},"severity":"NORMAL","state":"OPEN"}

Example response representations:

  • 201 - application/json (comment) [expand]

    Example
    {"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}

    The newly created comment.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The comment was not created due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request, create a comment or watch the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository, pull request or parent comment

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/blocker-comments?count&state

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Gets comments matching the given set of field values for the specified pull request. (Note this does not perform any kind of searching for comments by their text).

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

count

boolean

Default: false

if true only the count of the comments by state will be returned (and not the body of the comments).

state

string

(optional). If supplied, only comments with a state in the given list will be returned. The state can be OPEN or RESOLVED.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"start":0}

    A page of Comments from the supplied pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository or pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository or pull request does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/blocker-comments/{commentId}

resource-wide template parameters
parametervaluedescription

commentId

long

the ID of the comment to retrieve

Methods

DELETE

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/blocker-comments/{commentId}?version

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Delete a pull request comment. Anyone can delete their own comment. Only users with REPO_ADMIN and above may delete comments created by other users.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

version

int

Default: -1

The expected version of the comment. This must match the server's version of the comment or the delete will fail. To determine the current version of the comment, the comment should be fetched from the server prior to the delete. Look for the 'version' attribute in the returned JSON structure.

Example response representations:

  • 204 [expand]

    The operation was successful

  • 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 comment.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository or pull request.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The comment has replies or the version supplied does not match the current version.

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Update a comment, with the following restrictions:

  • only the author of the comment may update the text of the comment
  • only the author of the comment, the author of the pull request or repository admins and above may update the other fields of a comment

Convert a comment to a task or vice versa.

Comments can be converted to tasks by setting the 'severity' attribute to 'BLOCKER':

     {
     "severity": "BLOCKER"
     }
     

Tasks can be converted to comments by setting the 'severity' attribute to 'NORMAL':

     {
     "severity": "NORMAL"
     }
     

Resolve a blocker comment.

Blocker comments can be resolved by setting the 'state' attribute to 'RESOLVED':

     {
     "state": "RESOLVED"
     }
     

Note: the supplied JSON object must contain a version that must match the server's version of the comment or the update will fail. To determine the current version of the comment, the comment should be fetched from the server prior to the update. Look for the 'version' attribute in the returned JSON structure.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"version":0,"text":"A pithy comment.","severity":"NORMAL","state":"OPEN"}

Example response representations:

  • 200 - application/json (comment) [expand]

    Example
    {"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}

    The newly updated comment.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The comment was not updated due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request, update a comment or watch the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository, pull request or comment

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The comment version supplied does not match the current version.

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieves a pull request comment.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example response representations:

  • 200 - application/json (comment) [expand]

    Example
    {"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}

    The requested comment.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the comment

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository, pull request or comment

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/changes

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/changes?changeScope&sinceId&untilId&withComments

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Gets changes for the specified PullRequest.

If the changeScope query parameter is set to unreviewed, the application will attempt to stream unreviewed changes based on the lastReviewedCommit of the current user, which are the changes between the lastReviewedCommit and the latest commit of the source branch. The current user is considered to not have any unreviewed changes for the pull request when the lastReviewedCommit is either null (everything is unreviewed, so all changes are streamed), equal to the latest commit of the source branch (everything is reviewed), or no longer on the source branch (the source branch has been rebased). In these cases, the application will fall back to streaming all changes (the default), which is the effective diff for the pull request. The type of changes streamed can be determined by the changeScope parameter included in the properties map of the response.

Note: This resource is currently not paged. The server will return at most one page. The server will truncate the number of changes to either the request's page limit or an internal maximum, whichever is smaller. The start parameter of the page request is also ignored.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

changeScope

string

Default: ALL

UNREVIEWED to stream the unreviewed changes for the current user (if they exist); RANGE to stream changes between two arbitrary commits (requires sinceId and untilId); otherwise ALL to stream all changes (the default)

sinceId

string

the since commit hash to stream changes for a RANGE arbitrary change scope

untilId

string

the until commit hash to stream changes for a RANGE arbitrary change scope

withComments

boolean

Default: true

true to apply comment counts in the changes (the default); otherwise, false to stream changes without comment counts

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"contentId":"5c279d6c7a3a053a145905aa9682ce02c16449e9","fromContentId":"7b86ad1a05b4259b8fa54497a8be0bd359a405bd","path":{"components":["path","to","unreviewed","file.txt"],"parent":"path/to/unreviewed","name":"file.txt","extension":"txt","toString":"path/to/unreviewed/file.txt"},"executable":false,"percentUnchanged":98,"type":"MOVE","nodeType":"FILE","srcPath":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"srcExecutable":false,"links":{"self":[null]},"properties":{"unreviewedCommits":1}}],"start":0}

    A page of unreviewed Changes for the current user from the supplied pull request, including the unreviewedCommits in the properties map.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository or pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository or pull request does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments

Methods

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Add a new comment.

Comments can be added in a few places by setting different attributes:

General pull request comment:

     {
         "text": "An insightful general comment on a pull request."
     }
     
Reply to a comment:
     {
         "text": "A measured reply.",
         "parent": {
             "id": 1
         }
     }
     
General file comment:
     {
         "text": "An insightful general comment on a file.",
         "anchor": {
             "diffType": "RANGE",
             "fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd",
             "path": "path/to/file",
             "srcPath": "path/to/file",
             "toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b"
         }
     }
     
File line comment:
     {
         "text": "A pithy comment on a particular line within a file.",
         "anchor": {
             "diffType": "COMMIT",
             "line": 1,
             "lineType": "CONTEXT",
             "fileType": "FROM",
             "fromHash": "6df3858eeb9a53a911cd17e66a9174d44ffb02cd",
             "path": "path/to/file",
             "srcPath": "path/to/file",
             "toHash": "04c7c5c931b9418ca7b66f51fe934d0bd9b2ba4b"
         }
     }
     

Add a new task.

Tasks are just comments with the attribute 'severity' set to 'BLOCKER':

General pull request task:

     {
     "text": "A task on a pull request.",
     "severity": "BLOCKER"
     }
     

Add a pending comment.

Pending comments are just comments with the attribute 'state' set to 'PENDING':

Pending comment:

     {
        "text": "This is a pending comment",
        "state": "PENDING"
     }
     

For file and line comments, 'path' refers to the path of the file to which the comment should be applied and 'srcPath' refers to the path the that file used to have (only required for copies and moves). Also, fromHash and toHash refer to the sinceId / untilId (respectively) used to produce the diff on which the comment was added. Finally diffType refers to the type of diff the comment was added on. For backwards compatibility purposes if no diffType is provided and no fromHash/toHash pair is provided the diffType will be resolved to 'EFFECTIVE'. In any other cases the diffType is REQUIRED.

For line comments, 'line' refers to the line in the diff that the comment should apply to. 'lineType' refers to the type of diff hunk, which can be:

  • 'ADDED' - for an added line;
  • 'REMOVED' - for a removed line; or
  • 'CONTEXT' - for a line that was unmodified but is in the vicinity of the diff.
'fileType' refers to the file of the diff to which the anchor should be attached - which is of relevance when displaying the diff in a side-by-side way. Currently the supported values are:
  • 'FROM' - the source file of the diff
  • 'TO' - the destination file of the diff
If the current user is not a participant the user is added as a watcher of the pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"text":"An insightful comment.","parent":{"id":1,"severity":"NORMAL","state":"OPEN"},"anchor":{"line":1,"lineType":"CONTEXT","fileType":"FROM","path":"path/to/file","srcPath":"path/to/file"},"severity":"NORMAL","state":"OPEN"}

Example response representations:

  • 201 - application/json (comment) [expand]

    Example
    {"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}

    The newly created comment.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The comment was not created due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request, create a comment or watch the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository, pull request or parent comment

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments?anchorState&diffType&fromHash&path&state&toHash

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Gets comments for the specified pull request and path.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

anchorState

string

Default: ACTIVE

ACTIVE to stream the active comments; ORPHANED to stream the orphaned comments; ALL to stream both the active and the orphaned comments;

diffType

string

EFFECTIVE to stream the comments related to the effective diff of the pull request; RANGE to stream comments related to a commit range between two arbitrary commits (requires fromHash and toHash); COMMIT to stream comments related to a commit between two arbitrary commits (requires fromHash and toHash)

fromHash

string

the from commit hash to stream comments for a RANGE or COMMIT arbitrary change scope

path

string

the path to stream comments for a given path

state

string

toHash

string

the to commit hash to stream comments for a RANGE or COMMIT arbitrary change scope

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"start":0}

    A page of Comments from the supplied pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository or pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository or pull request does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments/{commentId}

resource-wide template parameters
parametervaluedescription

commentId

long

the ID of the comment to retrieve

Methods

DELETE

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments/{commentId}?version

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Delete a pull request comment. Anyone can delete their own comment. Only users with REPO_ADMIN and above may delete comments created by other users.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

version

int

Default: -1

The expected version of the comment. This must match the server's version of the comment or the delete will fail. To determine the current version of the comment, the comment should be fetched from the server prior to the delete. Look for the 'version' attribute in the returned JSON structure.

Example response representations:

  • 204 [expand]

    The operation was successful

  • 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 comment.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository or pull request.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The comment has replies or the version supplied does not match the current version.

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Update a comment, with the following restrictions:

  • only the author of the comment may update the text of the comment
  • only the author of the comment, the author of the pull request or repository admins and above may update the other fields of a comment

Convert a comment to a task or vice versa.

Comments can be converted to tasks by setting the 'severity' attribute to 'BLOCKER':

     {
     "severity": "BLOCKER"
     }
     

Tasks can be converted to comments by setting the 'severity' attribute to 'NORMAL':

     {
     "severity": "NORMAL"
     }
     

Resolve a task.

Tasks can be resolved by setting the 'state' attribute to 'RESOLVED':

     {
     "state": "RESOLVED"
     }
     

Note: the supplied JSON object must contain a version that must match the server's version of the comment or the update will fail. To determine the current version of the comment, the comment should be fetched from the server prior to the update. Look for the 'version' attribute in the returned JSON structure.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"version":0,"text":"A pithy comment.","severity":"NORMAL","state":"OPEN"}

Example response representations:

  • 200 - application/json (comment) [expand]

    Example
    {"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}

    The newly updated comment.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The comment was not updated due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request, update a comment or watch the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository, pull request or comment

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The comment version supplied does not match the current version.

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieves a pull request comment.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example response representations:

  • 200 - application/json (comment) [expand]

    Example
    {"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}

    The requested comment.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the comment

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository, pull request or comment

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments/{commentId}/apply-suggestion

Methods

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Apply a suggestion contained within a comment.

Example request representations:

  • application/json [expand]

    Example
    {"commentVersion":3,"message":"a commit message","pullRequestVersion":12,"suggestionIndex":0}

Example response representations:

  • 204 [expand]

    An empty response indicating the suggestion has been applied

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The suggestion was not applied due to a validation error

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to apply the suggestion

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied project, repository, pull request or parent comment

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    There was an error applying the suggestion to the source branch. It must be applied manually

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/commits

resource-wide template parameters
parametervaluedescription

pullRequestId

long

ID of the pullrequest, part of the path

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/commits?withCounts&avatarSize&avatarScheme

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve commits for the specified pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

withCounts

boolean

if set to true, the service will add "authorCount" and "totalCount" at the end of the page. "authorCount" is the number of different authors and "totalCount" is the total number of commits.

avatarSize

string

if present the service adds avatar URLs for commit authors. Should be an integer specifying the desired size in pixels. If the parameter is not present, avatar URLs will not be set

avatarScheme

string

the desired scheme for the avatar URL. If the parameter is not present URLs will use the same scheme as this request

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"id":"def0123abcdef4567abcdef8987abcdef6543abc","displayId":"def0123abcd","author":{"name":"charlie","emailAddress":"charlie@example.com"},"authorTimestamp":1646171633497,"committer":{"name":"charlie","emailAddress":"charlie@example.com"},"committerTimestamp":1646171633497,"message":"More work on feature 1","parents":[{"id":"abcdef0123abcdef4567abcdef8987abcdef6543","displayId":"abcdef0"}]}],"start":0,"authorCount":1,"totalCount":1}

    a page of commits from the supplied pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository or pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository or pull request does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/diff

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/diff?contextLines&sinceId&srcPath&untilId&whitespace

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Streams the raw diff for a pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

sinceId

string

srcPath

string

the previous path to the file, if the file has been copied, moved or renamed

untilId

string

whitespace

string

optional whitespace flag which can be set to ignore-all

Example response representations:

  • 200 - text/plain [expand]

    A raw diff for the specified pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the specified pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the pull request does not exist

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/diff?contextLines&diffType&sinceId&srcPath&untilId&whitespace&withComments

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Streams a diff within a pull request.

If the specified file has been copied, moved or renamed, the srcPath must also be specified to produce the correct diff.

Note: This RESTful endpoint is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

diffType

string

Default: EFFECTIVE

the type of diff being requested. When withComments is true this works as a hint to the system to attach the correct set of comments to the diff

sinceId

string

the since commit hash to stream a diff between two arbitrary hashes

srcPath

string

the previous path to the file, if the file has been copied, moved or renamed

untilId

string

the until commit hash to stream a diff between two arbitrary hashes

whitespace

string

optional whitespace flag which can be set to ignore-all

withComments

boolean

Default: true

true to embed comments in the diff (the default); otherwise, false to stream the diff without comments

Example response representations:

  • 200 - application/json (diffs) [expand]

    Example
    {"diffs":[{"source":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"destination":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"hunks":[{"sourceLine":1,"sourceSpan":1,"destinationLine":1,"destinationSpan":2,"segments":[{"type":"REMOVED","lines":[{"destination":1,"source":1,"line":"import sys","truncated":false}],"truncated":false},{"type":"ADDED","lines":[{"destination":1,"source":2,"line":"import re","truncated":false,"conflictMarker":"OURS","commentIds":[1]},{"destination":2,"source":3,"line":"import os","truncated":false}],"truncated":false}],"truncated":false}],"lineComments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}

    a page of differences from a pull request.

  • 400 - application/json (errors) [expand]

    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}]}

    If the request was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository or pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository or pull request does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/diff/{path:.*}

resource-wide template parameters
parametervaluedescription

path

string

the path to the file which should be diffed (optional)

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/diff/{path:.*}?contextLines&sinceId&srcPath&untilId&whitespace

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Streams the raw diff for a pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

sinceId

string

srcPath

string

the previous path to the file, if the file has been copied, moved or renamed

untilId

string

whitespace

string

optional whitespace flag which can be set to ignore-all

Example response representations:

  • 200 - text/plain [expand]

    A raw diff for the specified pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the specified pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the pull request does not exist

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/diff/{path:.*}?contextLines&diffType&sinceId&srcPath&untilId&whitespace&withComments&avatarSize&avatarScheme

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Streams a diff within a pull request.

If the specified file has been copied, moved or renamed, the srcPath must also be specified to produce the correct diff.

Note: This RESTful endpoint is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

request query parameters
parametervaluedescription

contextLines

int

Default: -1

the number of context lines to include around added/removed lines in the diff

diffType

string

Default: EFFECTIVE

the type of diff being requested. When withComments is true this works as a hint to the system to attach the correct set of comments to the diff

sinceId

string

the since commit hash to stream a diff between two arbitrary hashes

srcPath

string

the previous path to the file, if the file has been copied, moved or renamed

untilId

string

the until commit hash to stream a diff between two arbitrary hashes

whitespace

string

optional whitespace flag which can be set to ignore-all

withComments

boolean

Default: true

true to embed comments in the diff (the default); otherwise, false to stream the diff without comments

avatarSize

string

if present the service adds avatar URLs for comment authors where the provided value specifies the desired avatar size in pixels

avatarScheme

string

the security scheme for avatar URLs. If the scheme is not present then it is inherited from the request. It can be set to "https" to force the use of secure URLs

Example response representations:

  • 200 - application/json (diffs) [expand]

    Example
    {"diffs":[{"source":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"destination":{"components":["path","to","file.txt"],"parent":"path/to","name":"file.txt","extension":"txt","toString":"path/to/file.txt"},"hunks":[{"sourceLine":1,"sourceSpan":1,"destinationLine":1,"destinationSpan":2,"segments":[{"type":"REMOVED","lines":[{"destination":1,"source":1,"line":"import sys","truncated":false}],"truncated":false},{"type":"ADDED","lines":[{"destination":1,"source":2,"line":"import re","truncated":false,"conflictMarker":"OURS","commentIds":[1]},{"destination":2,"source":3,"line":"import os","truncated":false}],"truncated":false}],"truncated":false}],"lineComments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}],"truncated":"true","contextLines":"10","fromHash":"a0f224fd7bd5f28ea5a752d41b9c9f6372fc6d9e","toHash":"dc93f22caadcde35daf5cc2cd65d2738c87e31ca","whiteSpace":"SHOW"}

    a page of differences from a pull request.

  • 400 - application/json (errors) [expand]

    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}]}

    If the request was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository or pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository or pull request does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants

resource-wide template parameters
parametervaluedescription

pullRequestId

long

the id of the pull request within the repository

Methods

GET

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieves a page of the participants for a given pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example response representations:

  • 201 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":true,"status":"APPROVED"}],"start":0}

    Details of the participants in this pull request

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

DELETE

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants?username

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Unassigns a participant from the REVIEWER role they may have been given in a pull request.

If the participant has no explicit role this method has no effect.

Afterwards, the user will still remain a participant in the pull request but their role will be reduced to PARTICIPANT. This is because once made a participant of a pull request, a user will forever remain a participant. Only their role may be altered.

The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource.

Deprecated since 4.2. Use /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug} instead.

request query parameters
parametervaluedescription

username

string

the participant's user name

Example response representations:

  • 204 [expand]

    The update completed.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The request does not have the username

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Assigns a participant to an explicit role in pull request. Currently only the REVIEWER role may be assigned.

If the user is not yet a participant in the pull request, they are made one and assigned the supplied role.

If the user is already a participant in the pull request, their previous role is replaced with the supplied role unless they are already assigned the AUTHOR role which cannot be changed and will result in a Bad Request (400) response code.

The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"user":{"name":"charlie"},"role":"REVIEWER"}

Example response representations:

  • 201 - application/json (participant) [expand]

    Example
    {"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":false,"status":"UNAPPROVED"}

    The created or updated participant.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The request does not have the username and role, or is attempting an invalid assignment

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug}

resource-wide template parameters
parametervaluedescription

pullRequestId

long

the id of the pull request within the repository

userSlug

string

the slug for the user changing their status

pullRequestId

long

the id of the pull request within the repository

Methods

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Change the current user's status for a pull request. Implicitly adds the user as a participant if they are not already. If the current user is the author, this method will fail.

The possible values for status are UNAPPROVED, NEEDS_WORK, or APPROVED.

If the new status is NEEDS_WORK or APPROVED then the lastReviewedCommit for the participant will be updated to the latest commit of the source branch of the pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"user":{"name":"charlie"},"approved":true,"status":"APPROVED"}

Example response representations:

  • 201 - application/json (participant) [expand]

    Example
    {"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"lastReviewedCommit":"7549846524f8aed2bd1c0249993ae1bf9d3c9998","role":"REVIEWER","approved":true,"status":"APPROVED"}

    Details of the new participant

  • 400 - application/json (errors) [expand]

    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 specified status was invalid.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The pull request is not open.

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Unassigns a participant from the REVIEWER role they may have been given in a pull request.

If the participant has no explicit role this method has no effect.

Afterwards, the user will still remain a participant in the pull request but their role will be reduced to PARTICIPANT. This is because once made a participant of a pull request, a user will forever remain a participant. Only their role may be altered.

The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource.

Deprecated since 4.2. Use /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/participants/{userSlug} instead.

Example response representations:

  • 204 [expand]

    The update completed.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The request does not have the username

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/review

Methods

GET

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Get the {@link CommentThread threads} which have {@link Comment comments} that have a {@link CommentState#PENDING pending state} and are part of the pull request review for the authenticated user.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"properties":{"key":"value"},"id":1,"version":1,"text":"A measured reply.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633190,"updatedDate":1646171633190,"comments":[{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}}],"start":0}

    A page of Comments from the supplied pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository or pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository or pull request does not exist.

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Discard a pull request review for the authenticated user.

The authenticated user must have REPO_READ permission for the repository to call this resource.

Example response representations:

  • 204 [expand]

    The pull request review has been discarded

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to discard the the pull request review

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified pull request or repository does not exist.

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Complete a review on a pull request.

Example request representations:

  • application/json [expand]

    Example
    {"commentText":"general comment text","participantStatus":"approved"}

Example response representations:

  • 200 - application/json [expand]

    Example
    {
         "publishedCommentCount" : 1
     }

    getting back the number of published comments and completing the review on a pull request.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The request is invalid when there is no request body provided, or the participant status in the request is invalid.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request, update a comment or watch the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    There is no pull request review for the user to finish.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/tasks

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the tasks associated with a pull request.

Deprecated since 7.2. Tasks are now managed using Comments with BLOCKER severity. Use /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/blocker-comments instead

Example response representations:

  • 200 - application/json (task) [expand]

    Example
    {"size":2,"limit":25,"isLastPage":true,"values":[{"properties":{"diffAnchorPath":"path/to/file.txt"},"anchor":{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}},"author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633488,"id":98,"permittedOperations":{"deletable":true,"editable":true,"transitionable":true},"text":"Fix typos on the constructor's arguments","state":"OPEN"},{"properties":{"diffAnchorPath":"path/to/file.txt"},"anchor":{"properties":{"key":"value"},"id":5,"version":1,"text":"This class is deprecated.  Can you please use the replacement?","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}},"author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633488,"id":99,"permittedOperations":{"deletable":false,"editable":false,"transitionable":true},"text":"Remove usage of deprecated class","state":"RESOLVED"}],"start":0}

    A page of tasks associated with the pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the current user cannot access the pull request

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the pull request does not exist

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/tasks/count

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the total number of OPEN and RESOLVED tasks associated with a pull request.

Deprecated since 7.2. Tasks are now managed using Comments with BLOCKER severity. Use /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/blocker-comments?count=true instead.

Example response representations:

  • 200 - application/json (taskCount) [expand]

    Example
    {"open":5,"resolved":2}

    Total number of {@link TaskState#OPEN open} and {@link TaskState#RESOLVED resolved} tasks associated with the pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the current user cannot access the pull request

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the pull request does not exist

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/watch

Methods

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Remove the authenticated user as a watcher for the specified pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example response representations:

  • 204 [expand]

    The user is no longer watching the pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Add the authenticated user as a watcher for the specified pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource.

Example response representations:

  • 204 [expand]

    The user is now watching the pull request.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the pull request.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or pull request does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/raw

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the raw content for a file path at a specified revision.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Example response representations:

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/raw/{path:.*}

resource-wide template parameters
parametervaluedescription

path

string

the file path to retrieve content from

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/raw/{path:.*}?at&hardwrap&htmlEscape&includeHeadingId&markup

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the raw content for a file path at a specified revision.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

at

string

a specific commit or ref to retrieve the raw content at, or the default branch if not specified

hardwrap

string

(Optional) Whether the markup implementation should convert newlines to breaks. If not specified, the value of the markup.render.hardwrap property, which is true by default, will be used

htmlEscape

string

(Optional) true if HTML should be escaped in the input markup, false otherwise. If not specified, the value of the markup.render.html.escape property, which is true by default, will be used

includeHeadingId

string

(Optional) true if headings should contain an ID based on the heading content. If not specified, the value of the markup.render.headerids property, which is false by default, will be used

markup

string

if present or "true", triggers the raw content to be markup-rendered and returned as HTML; otherwise, if not specified, or any value other than "true", the content is streamed without markup

Example response representations:

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/ref-change-activities

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/ref-change-activities?ref

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of repository ref change activity.

The authenticated user must have REPO_ADMIN permission to call this resource.

request query parameters
parametervaluedescription

ref

string

(optional) exact match for a ref ID to filter ref change activity for

Example response representations:

  • 200 - application/json (refChangeActivity) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"id":1,"createdDate":1646171633689,"user":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"repository":{"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}},"trigger":"push","refChange":{"ref":{"id":"refs/heads/master","displayId":"master","type":"BRANCH"},"refId":"refs/heads/master","fromHash":"6053a1eaa1c009dd11092d09a72f3c41af1b59ad","toHash":"d6edcbf924697ab811a867421dab60d954ccad99","type":"UPDATE","updateType":"FORCED"}}],"start":0}

    A page of ref change activity

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The user is currently not authenticated or the user does not have {@link Permission#REPO_ADMIN REPO_ADMIN} permission.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/ref-change-activities/branches

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/ref-change-activities/branches?filterText

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of branches for a specific repository.

The authenticated user must have REPO_ADMIN permission to call this resource.

request query parameters
parametervaluedescription

filterText

string

(optional) partial match for a ref ID to filter minimal refs for

Example response representations:

  • 200 - application/json (minimalRef) [expand]

    Example
    {"id":"refs/heads/main","displayId":"main","type":"BRANCH"}

    A page of branches

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The user is currently not authenticated or the user does not have {@link Permission#REPO_ADMIN REPO_ADMIN} permission.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/pull-requests

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the pull request settings for the context repository.

The authenticated user must have REPO_READ permission for the context repository to call this resource.

This resource will call all RestFragments that are registered with the key bitbucket.repository.settings.pullRequests. If any fragment fails validations by returning a non-empty Map of errors, then no fragments will execute.

The property keys for the settings that are bundled with the application are

  • mergeConfig - the merge strategy configuration for pull requests
  • requiredApprovers - (Deprecated, please use com.atlassian.bitbucket.server.bundled-hooks.requiredApproversMergeHook instead) the number of approvals required on a pull request for it to be mergeable, or 0 if the merge check is disabled
  • com.atlassian.bitbucket.server.bundled-hooks.requiredApproversMergeHook - the merge check configuration for required approvers
  • requiredAllApprovers - whether or not all approvers must approve a pull request for it to be mergeable
  • requiredAllTasksComplete - whether or not all tasks on a pull request need to be completed for it to be mergeable
  • requiredSuccessfulBuilds - (Deprecated, please use com.atlassian.bitbucket.server.bitbucket-build.requiredBuildsMergeCheck instead) the number of successful builds on a pull request for it to be mergeable, or 0 if the merge check is disabled
  • com.atlassian.bitbucket.server.bitbucket-build.requiredBuildsMergeCheck - the merge check configuration for required builds

Example response representations:

  • 200 - application/json [expand]

    Example
    {"mergeConfig":{"commitSummaries":20,"defaultStrategy":{"description":"Always create a merge commit","enabled":true,"flag":"--no-ff","id":"no-ff","name":"Merge commit"},"strategies":[{"description":"Always create a merge commit","enabled":true,"flag":"--no-ff","id":"no-ff","name":"Merge commit"}],"type":"repository"},"requiredAllApprovers":false,"requiredAllTasksComplete":false,"com.atlassian.bitbucket.server.bundled-hooks.requiredApproversMergeHook":{"enabled":true,"count":2},"requiredApprovers":2,"com.atlassian.bitbucket.server.bitbucket-build.requiredBuildsMergeCheck":{"enabled":true,"count":3},"requiredSuccessfulBuilds":2}

    The repository pull request settings for the context 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 see the specified repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Update the pull request settings for the context repository.

The authenticated user must have REPO_ADMIN permission for the context repository to call this resource.

This resource will call all RestFragments that are registered with the key bitbucket.repository.settings.pullRequests. If any fragment fails validations by returning a non-empty Map of errors, then no fragments will execute.

Only the settings that should be updated need to be included in the request.

The property keys for the settings that are bundled with the application are

  • mergeConfig - the merge strategy configuration for pull requests
  • requiredApprovers - (Deprecated, please use com.atlassian.bitbucket.server.bundled-hooks.requiredApproversMergeHook instead) the number of approvals required on a pull request for it to be mergeable, or 0 to disable the merge check
  • com.atlassian.bitbucket.server.bundled-hooks.requiredApproversMergeHook - a json map containing the keys 'enabled' (a boolean to enable or disable this merge check) and 'count' (an integer to set the number of required approvals)
  • requiredAllApprovers - whether or not all approvers must approve a pull request for it to be mergeable
  • requiredAllTasksComplete - whether or not all tasks on a pull request need to be completed for it to be mergeable
  • requiredSuccessfulBuilds - (Deprecated, please use com.atlassian.bitbucket.server.bitbucket-build.requiredBuildsMergeCheck instead) the number of successful builds on a pull request for it to be mergeable, or 0 to disable the merge check
  • com.atlassian.bitbucket.server.bitbucket-build.requiredBuildsMergeCheck - a json map containing the keys 'enabled' (a boolean to enable or disable this merge check) and 'count' (an integer to set the number of required builds)
Merge strategy configuration deletion:

An explicitly set pull request merge strategy configuration can be deleted by POSTing a document with an empty "mergeConfig" attribute. i.e:

 {
     "mergeConfig": {
     }
 }
 
Upon completion of this request, the effective configuration will be:
  • The configuration set for this repository's SCM type as set at the project level, if present, otherwise
  • the configuration set for this repository's SCM type as set at the instance level, if present, otherwise
  • the default configuration for this repository's SCM type

Example request representations:

  • application/json [expand]

    Example
    {"mergeConfig":{"commitSummaries":20,"defaultStrategy":{"id":"no-ff"},"strategies":[{"id":"no-ff"}]},"requiredAllApprovers":false,"requiredAllTasksComplete":false,"com.atlassian.bitbucket.server.bundled-hooks.requiredApproversMergeHook":{"enabled":true,"count":2},"requiredApprovers":2,"com.atlassian.bitbucket.server.bitbucket-build.requiredBuildsMergeCheck":{"enabled":true,"count":3},"requiredSuccessfulBuilds":2}

Example response representations:

  • 200 - application/json (settings) [expand]

    Example
    {"mergeConfig":{"commitSummaries":20,"defaultStrategy":{"description":"Always create a merge commit","enabled":true,"flag":"--no-ff","id":"no-ff","name":"Merge commit"},"strategies":[{"description":"Always create a merge commit","enabled":true,"flag":"--no-ff","id":"no-ff","name":"Merge commit"}],"type":"repository"},"requiredAllApprovers":false,"requiredAllTasksComplete":false,"com.atlassian.bitbucket.server.bundled-hooks.requiredApproversMergeHook":{"enabled":true,"count":2},"requiredApprovers":2,"com.atlassian.bitbucket.server.bitbucket-build.requiredBuildsMergeCheck":{"enabled":true,"count":3},"requiredSuccessfulBuilds":2}

    The repository pull request settings for the context repository.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository pull request settings were not updated due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to see the specified repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/auto-decline

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieves the auto decline settings for the supplied repository. Project settings will be returned if no explicit settings have been set for the repository. In the case that there are no project settings, the default settings will be returned.

The authenticated user must have REPO_READ permission for this repository to call the resource.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"enabled":true,"inactivityWeeks":8,"scope":{"resourceId":2,"type":"REPOSITORY"}}

    The auto decline settings

  • 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 auto decline settings.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Delete auto decline settings for the supplied repository.

The authenticated user must have REPO_ADMIN permission for this repository to call the resource.

Example response representations:

  • 204 [expand]

    The auto decline settings have been deleted successfully.

  • 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 auto decline settings.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Creates or updates the auto decline settings for the supplied repository.

The authenticated user must have REPO_ADMIN permission for this repository to call the resource.

Example request representations:

  • application/json [expand]

    Example
    {"enabled":true,"inactivityWeeks":4}

Example response representations:

  • 200 - application/json [expand]

    Example
    {"enabled":true,"inactivityWeeks":8,"scope":{"resourceId":2,"type":"REPOSITORY"}}

    The auto decline settings

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    inactivityWeeks was not one of {@link DmzAutoDeclineSettingsService#VALID_INACTIVITY_WEEKS}

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to create or update the auto decline settings.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks?type

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of repository hooks for this repository.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

type

string

Default:

the optional type to filter by. Valid values are PRE_RECEIVE or POST_RECEIVE

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"details":{"key":"com.atlassian.stash.plugin.example:example-repository-hook","name":"Example repository hook","type":"PRE_RECEIVE","description":"An example description for an example hook.","version":"1.2.4","configFormKey":null,"scopeTypes":["PROJECT","REPOSITORY"]},"enabled":true,"configured":true,"scope":{"resourceId":2,"type":"REPOSITORY"}}],"start":0}

    returns a page of repository hooks with their associated enabled state.

  • 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 hooks.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}

resource-wide template parameters
parametervaluedescription

hookKey

string

the hook key

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a repository hook for this repository.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"details":{"key":"com.atlassian.stash.plugin.example:example-repository-hook","name":"Example repository hook","type":"PRE_RECEIVE","description":"An example description for an example hook.","version":"1.2.4","configFormKey":null,"scopeTypes":["PROJECT","REPOSITORY"]},"enabled":true,"configured":true,"scope":{"resourceId":2,"type":"REPOSITORY"}}

    returns the repository hooks with their associated enabled state for the supplied hookKey.

  • 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 hook.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository hook does not exist for the given repository, or the repository does not exist.

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Delete repository hook configuration for the supplied hookKey and repositorySlug

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Example response representations:

  • 204 [expand]

    The hook configuration matching the supplied hookKey and repositorySlug was 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 hook.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or hook does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}/enabled

resource-wide template parameters
parametervaluedescription

hookKey

string

the hook key

Methods

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Enable a repository hook for this repository and optionally apply new configuration.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

A JSON document may be provided to use as the settings for the hook. These structure and validity of the document is decided by the plugin providing the hook.

request header parameters
parametervaluedescription

Content-Length

int

Default: 0

the content length as generated by the client

Example response representations:

  • 200 - application/json [expand]

    Example
    {"details":{"key":"com.atlassian.stash.plugin.example:example-repository-hook","name":"Example repository hook","type":"PRE_RECEIVE","description":"An example description for an example hook.","version":"1.2.4","configFormKey":null,"scopeTypes":["PROJECT","REPOSITORY"]},"enabled":true,"configured":true,"scope":{"resourceId":2,"type":"REPOSITORY"}}

    returns the repository hooks with their associated enabled state for the supplied hookKey.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The settings specified are invalid.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to enable the hook.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or hook does not exist.

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Disable a repository hook for this repository.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"details":{"key":"com.atlassian.stash.plugin.example:example-repository-hook","name":"Example repository hook","type":"PRE_RECEIVE","description":"An example description for an example hook.","version":"1.2.4","configFormKey":null,"scopeTypes":["PROJECT","REPOSITORY"]},"enabled":true,"configured":true,"scope":{"resourceId":2,"type":"REPOSITORY"}}

    returns the repository hooks with their associated enabled state for the supplied hookKey.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to disable the hook.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or hook does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}/settings

resource-wide template parameters
parametervaluedescription

hookKey

string

the hook key

Methods

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Modify the settings for a repository hook for this repository.

The service will reject any settings which are too large, the current limit is 32KB once serialized.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

A JSON document can be provided to use as the settings for the hook. These structure and validity of the document is decided by the plugin providing the hook.

Example request representations:

  • application/json [expand]

    Example
    {"string-value":"this is an arbitrary string","integer-value":1,"long-value":2147483648,"boolean-value":true,"double-value":1.1}

Example response representations:

  • 200 - application/json [expand]

    Example
    {"string-value":"this is an arbitrary string","integer-value":1,"long-value":2147483648,"boolean-value":true,"double-value":1.1}

    The settings for the hook.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The settings specified are invalid.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to modify the hook settings.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or hook does not exist.

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the settings for a repository hook for this repository.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"string-value":"this is an arbitrary string","integer-value":1,"long-value":2147483648,"boolean-value":true,"double-value":1.1}

    The settings for the hook.

  • 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 hook settings.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository or hook does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/reviewer-groups

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a page of reviewer groups of a given scope.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Example response representations:

  • 200 - application/json (reviewer group) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"description":null,"id":1,"name":"name","scope":{"resourceId":2,"type":"REPOSITORY"},"type":"REVIEWER_GROUP","users":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}]}],"start":0}

    A page of reviewer group(s) of the provided scope and its inherited scope

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository scope supplied does not exist.

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Create a reviewer group.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Example request representations:

Example response representations:

  • 201 - application/json (reviewer group) [expand]

    Example
    {"description":null,"id":1,"name":"name","scope":{"resourceId":2,"type":"REPOSITORY"},"type":"REVIEWER_GROUP","users":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}]}

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The request is missing a reviewer group name.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository scope supplied does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The new created name already exists.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/reviewer-groups/{id}

resource-wide template parameters
parametervaluedescription

id

long

the ID of the reviewer group to be deleted

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a reviewer group.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Example response representations:

  • 200 - application/json (reviewer group) [expand]

    Example
    {"description":null,"id":1,"name":"name","scope":{"resourceId":2,"type":"REPOSITORY"},"type":"REVIEWER_GROUP","users":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}]}

    A page of changes

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The ID supplied does not exist

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Update the attributes of a reviewer group.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Example request representations:

Example response representations:

  • 200 - application/json (reviewer group) [expand]

    Example
    {"description":null,"id":1,"name":"name","scope":{"resourceId":2,"type":"REPOSITORY"},"type":"REVIEWER_GROUP","users":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}]}

    A page of changes

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The updated attribute does not meet the requirements. e.g. the name exceeds 50 characters, setting name to blank

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository scope supplied does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The new updated name already exists.

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Delete a reviewer group.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Example response representations:

  • 204 [expand]

    The operation was successful

  • 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 reviewer group in this repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied reviewer group ID.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/reviewer-groups/{id}/users

resource-wide template parameters
parametervaluedescription

id

long

the ID of the reviewer group to be retrieved

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the users of a reviewer group

This does not return all the users of the group, only the users who have REPO_READ permission for the specified repository.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Example response representations:

  • 200 - application/json (reviewer group) [expand]

    Example
    [{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}]

    A page of changes

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The ID supplied does not exist

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/tags

Methods

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Creates a tag using the information provided in the {@link RestCreateTagRequest request}

The authenticated user must have REPO_WRITE permission for the context repository to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"name":"my-tag","startPoint":"8d351a10fb428c0c1239530256e21cf24f136e73","message":"This is my tag"}

Example response representations:

  • 200 - application/json (tag) [expand]

    Example
    {"id":"release-2.0.0","displayId":"refs/tags/release-2.0.0","type":"TAG","latestCommit":"8d351a10fb428c0c1239530256e21cf24f136e73","latestChangeset":"8d351a10fb428c0c1239530256e21cf24f136e73","hash":"8d51122def5632836d1cb1026e879069e10a1e13"}

    The created tag

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to write 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.

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/tags?filterText&orderBy

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve the tags matching the supplied filterText param.

The authenticated user must have REPO_READ permission for the context repository to call this resource.

request query parameters
parametervaluedescription

filterText

string

the text to match on

orderBy

string

ordering of refs either ALPHABETICAL (by name) or MODIFICATION (last updated)

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"id":"release-2.0.0","displayId":"refs/tags/release-2.0.0","type":"TAG","latestCommit":"8d351a10fb428c0c1239530256e21cf24f136e73","latestChangeset":"8d351a10fb428c0c1239530256e21cf24f136e73","hash":"8d51122def5632836d1cb1026e879069e10a1e13"}],"start":0}

    The tags matching the supplied filterText.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to read 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/api/1.0/projects/{projectKey}/repos/{repositorySlug}/tags/{name:.*}

resource-wide template parameters
parametervaluedescription

name

string

the name of the tag to be retrieved

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Retrieve a tag in the specified repository.

The authenticated user must have REPO_READ permission for the context repository to call this resource.

Example response representations:

  • 200 - application/json (tag) [expand]

    Example
    {"id":"release-2.0.0","displayId":"refs/tags/release-2.0.0","type":"TAG","latestCommit":"8d351a10fb428c0c1239530256e21cf24f136e73","latestChangeset":"8d351a10fb428c0c1239530256e21cf24f136e73","hash":"8d51122def5632836d1cb1026e879069e10a1e13"}

    The tag which matches the supplied name.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to read the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified tag does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/watch

Methods

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Remove the authenticated user as a watcher for the specified repository.

The authenticated user must have REPO_READ permission for the repository to call this resource.

Example response representations:

  • 204 [expand]

    The user is no longer watching 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 view the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Add the authenticated user as a watcher for the specified repository.

The authenticated user must have REPO_READ permission for the repository to call this resource.

Example response representations:

  • 204 [expand]

    The user is now watching 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 view 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/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks?event&statistics

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Find webhooks in this repository.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

event

string

list of {@link com.atlassian.webhooks.WebhookEvent} ids to filter for

statistics

boolean

Default: false

true if statistics should be provided for all found webhooks

Example response representations:

  • 200 - application/json (webhook) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"id":10,"name":"Webhook Name","createdDate":1513106011000,"updatedDate":1513106011000,"events":["repo:refs_changed","repo:modified"],"configuration":{"secret":"password"},"url":"http://example.com","active":true}],"start":0}

    A list of webhooks.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to find webhooks in the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Create a webhook for the repository specified via the URL.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Example request representations:

  • application/json [expand]

    Example
    {"id":10,"name":"Webhook Name","createdDate":1513106011000,"updatedDate":1513106011000,"events":["repo:refs_changed","repo:modified"],"configuration":{"secret":"password"},"url":"http://example.com","active":true}

Example response representations:

  • 200 - application/json (webhook) [expand]

    Example
    {"id":10,"name":"Webhook Name","createdDate":1513106011000,"updatedDate":1513106011000,"events":["repo:refs_changed","repo:modified"],"configuration":{"secret":"password"},"url":"http://example.com","active":true}

    A created webhook.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The webhook parameters were invalid or not supplied.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to create webhooks in the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/test

Methods

POST

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/test?url

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Test connectivity to a specific endpoint.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

url

string

the url in which to connect to

Example response representations:

  • 200 - application/json (webhook) [expand]

    Example
    {"request":{"url":"http://example.com/callback","body":null,"method":"POST","headers":{"Accept":"*/*"}},"response":{"status":200,"headers":{"Content-Type":"application/json"},"body":"{\n  \"accepted\": true\n}"}}

    a webhook.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to test a connection.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}

resource-wide template parameters
parametervaluedescription

webhookId

int

the existing webhook id

Methods

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Delete a webhook for the repository specified via the URL.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Example response representations:

  • 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 webhooks in the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist, or webhook does not exist in this repository.

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}?statistics

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Get a webhook by id.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

statistics

boolean

Default: false

statistics

Example response representations:

  • 200 - application/json (webhook) [expand]

    Example
    {"id":10,"name":"Webhook Name","createdDate":1513106011000,"updatedDate":1513106011000,"events":["repo:refs_changed","repo:modified"],"configuration":{"secret":"password"},"url":"http://example.com","active":true}

    a webhook.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to get a webhook in the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist, or the webhook does not exist in the repository.

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Update an existing webhook.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Example request representations:

Example response representations:

  • 200 - application/json (webhook) [expand]

    Example
    {"id":10,"name":"Webhook Name","createdDate":1513106011000,"updatedDate":1513106011000,"events":["repo:refs_changed","repo:modified"],"configuration":{"secret":"password"},"url":"http://example.com","active":true}

    a webhook.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update a webhook in this repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist, or the webhook does not exist in the repository.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}/latest

resource-wide template parameters
parametervaluedescription

webhookId

int

id of the webhook

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}/latest?event&outcome

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Get the latest invocations for a specific webhook.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

event

string

the string id of a specific event to retrieve the last invocation for.

outcome

string

the outcome to filter for. Can be SUCCESS, FAILURE, ERROR. None specified means that the all will be considered

Example response representations:

  • 200 - application/json (webhookInvocation) [expand]

    Example
    {"id":10,"event":"repo:created","duration":155,"start":1513106011,"finish":1513106166,"request":{"method":"POST","url":"http://example.com/callback"},"result":{"description":"200","outcome":"SUCCESS"}}

    a webhook invocation dataset.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to get webhook invocations in the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist, or the webhook does not exist in the repository.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}/statistics

resource-wide template parameters
parametervaluedescription

webhookId

int

id of the webhook

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}/statistics?event

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Get the statistics for a specific webhook.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

request query parameters
parametervaluedescription

event

string

the string id of a specific event to retrieve the last invocation for. May be empty, in which case all events are considered

Example response representations:

  • 200 - application/json (webhookInvocation) [expand]

    Example
    {"lastSuccess":{"id":10,"event":"repo:created","duration":155,"start":1513106011,"finish":1513106166,"request":{"method":"POST","url":"http://example.com/callback"},"result":{"description":"200","outcome":"SUCCESS"}},"lastFailure":{"id":11,"event":"repo:refs_changed","duration":100,"start":1513106011,"finish":1513106111,"request":{"method":"POST","url":"http://example.com/callback"},"result":{"description":"404","outcome":"FAILURE"}},"lastError":{"id":12,"event":"repo:modified","duration":100,"start":1513106011,"finish":1513106111,"request":{"method":"POST","url":"http://example.com/callback"},"result":{"description":"Detailed error message","outcome":"ERROR"}},"counts":100}

    a webhook invocation dataset.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to get webhook statistics in the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist, or the webhook does not exist in the repository.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/webhooks/{webhookId}/statistics/summary

resource-wide template parameters
parametervaluedescription

webhookId

int

id of the webhook

Methods

GET

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.

Get the statistics summary for a specific webhook.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Example response representations:

  • 200 - application/json (webhookInvocation) [expand]

    Example
    {"lastSuccess":{"id":10,"event":"repo:created","duration":155,"start":1513106011,"finish":1513106166,"request":{"method":"POST","url":"http://example.com/callback"},"result":{"description":"200","outcome":"SUCCESS"}},"lastFailure":{"id":11,"event":"repo:refs_changed","duration":100,"start":1513106011,"finish":1513106111,"request":{"method":"POST","url":"http://example.com/callback"},"result":{"description":"404","outcome":"FAILURE"}},"lastError":{"id":12,"event":"repo:modified","duration":100,"start":1513106011,"finish":1513106111,"request":{"method":"POST","url":"http://example.com/callback"},"result":{"description":"Detailed error message","outcome":"ERROR"}},"counts":100}

    a webhook invocation dataset.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to get webhook statistics summary in the repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository does not exist, or the webhook does not exist in the repository.

/rest/api/1.0/projects/{projectKey}/settings/pull-requests/{scmId}

resource-wide template parameters
parametervaluedescription

scmId

string

the SCM to get strategies for

Methods

GET

This is a paged API.

Retrieve the merge strategy configuration for this project and SCM.

The authenticated user must have PROJECT_READ permission for the context repository to call this resource.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"mergeConfig":{"commitSummaries":20,"defaultStrategy":{"description":"Always create a merge commit","enabled":true,"flag":"--no-ff","id":"no-ff","name":"Merge commit"},"strategies":[{"description":"Always create a merge commit","enabled":true,"flag":"--no-ff","id":"no-ff","name":"Merge commit"}],"type":"repository"}}

    The merge configuration of the request 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 see the request repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The request repository does not exist.

POST

Update the pull request merge strategy configuration for this project and SCM.

The authenticated user must have PROJECT_ADMIN permission for the context repository to call this resource.

Only the strategies provided will be enabled, the default must be set and included in the set of strategies.

An explicitly set pull request merge strategy configuration can be deleted by POSTing a document with an empty "mergeConfig" attribute. i.e:

 {
     "mergeConfig": {
     }
 }
 
Upon completion of this request, the effective configuration will be the configuration explicitly set for the SCM, or if no such explicit configuration is set then the default configuration will be used.

Example request representations:

  • application/json [expand]

    Example
    {"mergeConfig":{"commitSummaries":20,"defaultStrategy":{"id":"no-ff"},"strategies":[{"id":"no-ff"}]}}

Example response representations:

  • 200 - application/json (strategies) [expand]

    Example
    {"mergeConfig":{"commitSummaries":20,"defaultStrategy":{"description":"Always create a merge commit","enabled":true,"flag":"--no-ff","id":"no-ff","name":"Merge commit"},"strategies":[{"description":"Always create a merge commit","enabled":true,"flag":"--no-ff","id":"no-ff","name":"Merge commit"}],"type":"repository"}}

    The repository pull request merge strategies for the context repository.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The repository pull request merge strategies were not updated due to a validation error.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to administrate the specified repository.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository does not exist.

/rest/api/1.0/projects/{projectKey}/settings/auto-decline

Methods

GET

Retrieves the auto decline settings for the supplied project. Default settings are returned if no explicit settings have been set for the project.

The authenticated user must have PROJECT_VIEW permission for this project to call the resource.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"enabled":true,"inactivityWeeks":8,"scope":{"resourceId":2,"type":"REPOSITORY"}}

    The auto decline settings

  • 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 auto decline settings.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project does not exist.

DELETE

Delete auto decline settings for the supplied project.

The authenticated user must have PROJECT_ADMIN permission for this project to call the resource.

Example response representations:

  • 204 [expand]

    The auto decline settings have been deleted successfully.

  • 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 auto decline settings.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project does not exist.

PUT

Creates or updates the auto decline settings for the supplied project.

The authenticated user must have PROJECT_ADMIN permission for this project to call the resource.

Example request representations:

  • application/json [expand]

    Example
    {"enabled":true,"inactivityWeeks":4}

Example response representations:

  • 200 - application/json [expand]

    Example
    {"enabled":true,"inactivityWeeks":8,"scope":{"resourceId":2,"type":"REPOSITORY"}}

    The auto decline settings

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    inactivityWeeks was not one of {@link DmzAutoDeclineSettingsService#VALID_INACTIVITY_WEEKS}

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to create or update the auto decline settings.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project does not exist.

/rest/api/1.0/projects/{projectKey}/settings/hooks

Methods

GET

/rest/api/1.0/projects/{projectKey}/settings/hooks?type

This is a paged API.

Retrieve a page of repository hooks for this project.

The authenticated user must have PROJECT_READ permission for the specified project to call this resource.

request query parameters
parametervaluedescription

type

string

Default:

the optional type to filter by. Valid values are PRE_RECEIVE or POST_RECEIVE

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"details":{"key":"com.atlassian.stash.plugin.example:example-repository-hook","name":"Example repository hook","type":"PRE_RECEIVE","description":"An example description for an example hook.","version":"1.2.4","configFormKey":null,"scopeTypes":["PROJECT","REPOSITORY"]},"enabled":true,"configured":true,"scope":{"resourceId":2,"type":"REPOSITORY"}}],"start":0}

    returns a page of repository hooks with their associated enabled state.

  • 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 hooks.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project does not exist.

/rest/api/1.0/projects/{projectKey}/settings/hooks/{hookKey}

resource-wide template parameters
parametervaluedescription

hookKey

string

the hook key

Methods

GET

Retrieve a repository hook for this project.

The authenticated user must have PROJECT_READ permission for the specified project to call this resource.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"details":{"key":"com.atlassian.stash.plugin.example:example-repository-hook","name":"Example repository hook","type":"PRE_RECEIVE","description":"An example description for an example hook.","version":"1.2.4","configFormKey":null,"scopeTypes":["PROJECT","REPOSITORY"]},"enabled":true,"configured":true,"scope":{"resourceId":2,"type":"REPOSITORY"}}

    returns the repository hooks with their associated enabled state for the supplied hookKey.

  • 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 hook.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified repository hook does not exist for the given project, or the project does not exist.

/rest/api/1.0/projects/{projectKey}/settings/hooks/{hookKey}/enabled

resource-wide template parameters
parametervaluedescription

hookKey

string

the hook key

Methods

PUT

Enable a repository hook for this project and optionally apply new configuration.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

A JSON document may be provided to use as the settings for the hook. These structure and validity of the document is decided by the plugin providing the hook.

request header parameters
parametervaluedescription

Content-Length

int

Default: 0

the content length

Example response representations:

  • 200 - application/json [expand]

    Example
    {"details":{"key":"com.atlassian.stash.plugin.example:example-repository-hook","name":"Example repository hook","type":"PRE_RECEIVE","description":"An example description for an example hook.","version":"1.2.4","configFormKey":null,"scopeTypes":["PROJECT","REPOSITORY"]},"enabled":true,"configured":true,"scope":{"resourceId":2,"type":"REPOSITORY"}}

    returns the repository hooks with their associated enabled state for the supplied hookKey.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The settings specified are invalid.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to enable the hook.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project or hook does not exist.

DELETE

Disable a repository hook for this project.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"details":{"key":"com.atlassian.stash.plugin.example:example-repository-hook","name":"Example repository hook","type":"PRE_RECEIVE","description":"An example description for an example hook.","version":"1.2.4","configFormKey":null,"scopeTypes":["PROJECT","REPOSITORY"]},"enabled":true,"configured":true,"scope":{"resourceId":2,"type":"REPOSITORY"}}

    returns the repository hooks with their associated enabled state for the supplied hookKey.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to disable the hook.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project or hook does not exist.

/rest/api/1.0/projects/{projectKey}/settings/hooks/{hookKey}/settings

resource-wide template parameters
parametervaluedescription

hookKey

string

the hook key

Methods

PUT

Modify the settings for a repository hook for this project.

The service will reject any settings which are too large, the current limit is 32KB once serialized.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

A JSON document can be provided to use as the settings for the hook. These structure and validity of the document is decided by the plugin providing the hook.

Example request representations:

  • application/json [expand]

    Example
    {"string-value":"this is an arbitrary string","integer-value":1,"long-value":2147483648,"boolean-value":true,"double-value":1.1}

Example response representations:

  • 200 - application/json [expand]

    Example
    {"string-value":"this is an arbitrary string","integer-value":1,"long-value":2147483648,"boolean-value":true,"double-value":1.1}

    The settings for the hook.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The settings specified are invalid.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to modify the hook settings.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project or hook does not exist.

GET

Retrieve the settings for a repository hook for this project.

The authenticated user must have PROJECT_READ permission for the specified project to call this resource.

Example response representations:

  • 200 - application/json [expand]

    Example
    {"string-value":"this is an arbitrary string","integer-value":1,"long-value":2147483648,"boolean-value":true,"double-value":1.1}

    The settings for the hook.

  • 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 hook settings.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified project or hook does not exist.

/rest/api/1.0/projects/{projectKey}/settings/reviewer-groups

Methods

GET

Retrieve a page of reviewer groups of a given scope.

The authenticated user must have PROJECT_READ permission for the specified project to call this resource.

Example response representations:

  • 200 - application/json (reviewer group) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"description":null,"id":1,"name":"name","scope":{"resourceId":2,"type":"REPOSITORY"},"type":"REVIEWER_GROUP","users":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}]}],"start":0}

    A page of reviewer group(s) of the provided scope

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the project.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The project scope supplied does not exist.

POST

Create a reviewer group.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Example request representations:

Example response representations:

  • 201 - application/json (reviewer group) [expand]

    Example
    {"description":null,"id":1,"name":"name","scope":{"resourceId":2,"type":"REPOSITORY"},"type":"REVIEWER_GROUP","users":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}]}

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The request is missing a reviewer group name.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the project.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The project scope supplied does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The new created name already exists.

/rest/api/1.0/projects/{projectKey}/settings/reviewer-groups/{id}

resource-wide template parameters
parametervaluedescription

id

long

the ID of the reviewer group to be deleted

Methods

GET

Retrieve a reviewer group.

The authenticated user must have PROJECT_READ permission for the specified project to call this resource.

Example response representations:

  • 200 - application/json (reviewer group) [expand]

    Example
    {"description":null,"id":1,"name":"name","scope":{"resourceId":2,"type":"REPOSITORY"},"type":"REVIEWER_GROUP","users":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}]}

    A page of changes

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the project.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The ID supplied does not exist

PUT

Update the attributes of a reviewer group.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Example request representations:

Example response representations:

  • 200 - application/json (reviewer group) [expand]

    Example
    {"description":null,"id":1,"name":"name","scope":{"resourceId":2,"type":"REPOSITORY"},"type":"REVIEWER_GROUP","users":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}]}

    A page of changes

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The updated attribute does not meet the requirements. e.g. the name exceeds 50 characters, setting name to blank

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the project.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The project scope supplied does not exist.

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The new updated name already exists.

DELETE

Delete a reviewer group.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Example response representations:

  • 204 [expand]

    The operation was successful

  • 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 reviewer group in this project.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Unable to find the supplied reviewer group ID.

/rest/api/1.0/repos

REST resource for searching through repositories

Methods

GET

/rest/api/1.0/repos?name&projectname&permission&state&visibility

This is a paged API.

Retrieve a page of repositories based on query parameters that control the search. See the documentation of the parameters for more details.

This resource is anonymously accessible.

Note on permissions. In absence of the permission query parameter the implicit 'read' permission is assumed. Please note that this permission is lower than the REPO_READ permission rather than being equal to it. The implicit 'read' permission for a given repository is assigned to any user that has any of the higher permissions, such as REPO_READ, as well as to anonymous users if the repository is marked as public. The important implication of the above is that an anonymous request to this resource with a permission level REPO_READ is guaranteed to receive an empty list of repositories as a result. For anonymous requests it is therefore recommended to not specify the permission parameter at all.

request query parameters
parametervaluedescription

name

string

(optional) if specified, this will limit the resulting repository list to ones whose name matches this parameter's value. The match will be done case-insensitive and any leading and/or trailing whitespace characters on the name parameter will be stripped.

projectname

string

(optional) if specified, this will limit the resulting repository list to ones whose project's name matches this parameter's value. The match will be done case-insensitive and any leading and/or trailing whitespace characters on the projectname parameter will be stripped.

permission

string

(optional) if specified, it must be a valid repository permission level name and will limit the resulting repository list to ones that the requesting user has the specified permission level to. If not specified, the default implicit 'read' permission level will be assumed. The currently supported explicit permission values are REPO_READ, REPO_WRITE and REPO_ADMIN.

state

string

(optional) if specified, it must be a valid repository state name and will limit the resulting repository list to ones that are in the specified state. The currently supported explicit state values are AVAILABLE, INITIALISING and INITIALISATION_FAILED.
Available since 5.13

visibility

string

(optional) if specified, this will limit the resulting repository list based on the repositories visibility. Valid values are public or private.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"slug":"my-repo","id":1,"name":"My repo","description":"My repo description","hierarchyId":"e3c939f9ef4a7fae272e","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"}]}}],"start":0}

    A page of repositories.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The visibility parameter contains an invalid value

/rest/api/1.0/tasks

Methods

POST

Create a new task.

Deprecated since 7.2. Tasks are now managed using Comments with severity BLOCKER. Call POST /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments instead, passing the attribute 'severity' set to 'BLOCKER'.

Example request representations:

  • application/json [expand]

    Example
    {"anchor":{"id":1,"type":"COMMENT"},"text":"Fix the missing imports"}

Example response representations:

  • 201 - application/json (task) [expand]

    Example
    {"anchor":{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}},"author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633487,"id":99,"permittedOperations":{"deletable":true,"editable":true,"transitionable":true},"text":"Fix the missing imports"}

    A copy of the created task.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the task data is invalid (for example, if the task's text is missing or blank)

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the anchor of the task (such as a pull request comment) does not exist or is not visible to the current user

/rest/api/1.0/tasks/{taskId}

resource-wide template parameters
parametervaluedescription

taskId

long

the id identifying the task to delete

Methods

DELETE

Delete a task.

Deprecated since 7.2. Tasks are now managed using Comments with BLOCKER severity. Call DELETE /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments/{commentId} instead.

Example response representations:

  • 204 (task) [expand]

    if the task was successfully deleted.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the current user does not have the permission to delete the task

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the task does not exist

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the task to delete is in the resolved state

PUT

Update an existing task.

Deprecated since 7.2. Tasks are now managed using Comments with BLOCKER severity. Call PUT /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments/{commentId} instead. To resolve a task, pass the attribute 'state' set to 'RESOLVED'.

Example request representations:

  • application/json [expand]

    Example
    {"id":99,"text":"Fix the missing and obsolete imports"}

Example response representations:

  • 200 - application/json (task) [expand]

    Example
    {"properties":{"diffAnchorPath":"path/to/file.txt"},"anchor":{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}},"author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633487,"id":99,"permittedOperations":{"deletable":true,"editable":true,"transitionable":true},"text":"Fix the missing and deprecated imports","state":"OPEN"}

    A copy of the task if it was successfully updated.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the current user does not have the permission to update the task

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the task does not exist

  • 409 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the task to update is in the resolved state

GET

Retrieve an existing task.

Deprecated since 7.2. Tasks are now managed using Comments with BLOCKER severity. Call GET /rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments/{commentId} instead.

Example response representations:

  • 200 - application/json (task) [expand]

    Example
    {"properties":{"diffAnchorPath":"path/to/file.txt"},"anchor":{"properties":{"key":"value"},"id":1,"version":1,"text":"An insightful comment.","author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633188,"updatedDate":1646171633188,"comments":[],"tasks":[],"severity":"NORMAL","state":"OPEN","permittedOperations":{"editable":true,"deletable":true}},"author":{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"},"createdDate":1646171633488,"id":99,"permittedOperations":{"deletable":false,"editable":false,"transitionable":true},"text":"Resolve the merge conflicts","state":"OPEN"}

    A copy of the task.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    If the task does not exist

/rest/api/1.0/users

Methods

GET

This is a paged API.

Retrieve a page of users, optionally run through provided filters.

Only authenticated users may call this resource.

Supported Filters

Filters are provided in query parameters in a standard name=value fashion. The following filters are currently supported:

  • filter - return only users, whose username, name or email address contain the filter value
  • group - return only users who are members of the given group
  • permission - the "root" of a permission filter, whose value must be a valid global, project, or repository permission. Additional filter parameters referring to this filter that specify the resource (project or repository) to apply the filter to must be prefixed with permission.. See the section "Permission Filters" below for more details.
  • permission.N - the "root" of a single permission filter, similar to the permission parameter, where "N" is a natural number starting from 1. This allows clients to specify multiple permission filters, by providing consecutive filters as permission.1, permission.2 etc. Note that the filters numbering has to start with 1 and be continuous for all filters to be processed. The total allowed number of permission filters is 50 and all filters exceeding that limit will be dropped. See the section "Permission Filters" below for more details on how the permission filters are processed.

Permission Filters

The following three sub-sections list parameters supported for permission filters (where [root] is the root permission filter name, e.g. permission, permission.1 etc.) depending on the permission resource. The system determines which filter to apply (Global, Project or Repository permission) based on the [root] permission value. E.g. ADMIN is a global permission, PROJECT_ADMIN is a project permission and REPO_ADMIN is a repository permission. Note that the parameters for a given resource will be looked up in the order as they are listed below, that is e.g. for a project resource, if both projectId and projectKey are provided, the system will use projectId for the lookup.

Global permissions

The permission value under [root] is the only required and recognized parameter, as global permissions do not apply to a specific resource.

Example valid filter: permission=ADMIN.

Project permissions

  • [root]- specifies the project permission
  • [root].projectId - specifies the project ID to lookup the project by
  • [root].projectKey - specifies the project key to lookup the project by

Example valid filter: permission.1=PROJECT_ADMIN&permission.1.projectKey=TEST_PROJECT.

Repository permissions

  • [root]- specifies the repository permission
  • [root].projectId - specifies the repository ID to lookup the repository by
  • [root].projectKey and [root].repositorySlug- specifies the project key and repository slug to lookup the repository by; both values need to be provided for this look up to be triggered
Example valid filter: permission.2=REPO_ADMIN&permission.2.projectKey=TEST_PROJECT&permission.2.repositorySlug=test_repo.

Example response representations:

  • 200 - application/json (page) [expand]

    Example
    {"size":1,"limit":25,"isLastPage":true,"values":[{"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}],"start":0}

    A page of users.

  • 400 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The search request was invalid, which may happen for multiple reasons, among others:

    • permission filter for project/repository permission with no parameters specifying the project or repository to apply the filter to
    • invalid permission name
    • permission filter for a project/repository permission pointing to a non-existent project or repository
    The exact reason for the error and - in most cases - the request parameter name that had invalid value - will be provided in the error message.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Authentication failed or was not attempted.

PUT

Update the currently authenticated user's details. The update will always be applied to the currently authenticated user.

Example request representations:

  • application/json [expand]

    Example
    {"name":null,"displayName":"Jane Citizen","email":"jane@example.com"}

Example response representations:

  • 200 - application/json (detailedUser) [expand]

    Example
    {"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}

    The updated user.

  • 400 - application/json (errors) [expand]

    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 was malformed.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Authentication failed or was not attempted.

/rest/api/1.0/users/credentials

Methods

PUT

Update the currently authenticated user's password.

Example request representations:

  • application/json [expand]

    Example
    {"password":"secret","passwordConfirm":"secret","oldPassword":"faithless"}

Example response representations:

  • 204 [expand]

    The user's password was successfully updated.

  • 400 - application/json (errors) [expand]

    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 was malformed or the old password was incorrect.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    Authentication failed or was not attempted.

/rest/api/1.0/users/{userSlug}

Methods

GET

Retrieve the user matching the supplied userSlug.

Example response representations:

  • 200 - application/json (userSlug) [expand]

    Example
    {"name":"jcitizen","emailAddress":"jane@example.com","id":101,"displayName":"Jane Citizen","active":true,"slug":"jcitizen","type":"NORMAL"}

    The user matching the supplied userSlug. Note, this may not be the user's username, always use the user.slug property.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to view the user.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user does not exist.

/rest/api/1.0/users/{userSlug}/avatar.png

Methods

DELETE

Delete the avatar associated to a user.

Users are always allowed to delete their own avatar. To delete someone else's avatar the authenticated user must have global ADMIN permission, or global SYS_ADMIN permission to update a SYS_ADMIN user's avatar.

Example response representations:

  • 200 - application/json (href) [expand]

    Example
    {"href":"http://www.gravatar.com/avatar/aa99b351245441b8ca95d54a52d2998c"}

    The new avatar URL if the local avatar was successfully deleted or did not exist

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The authenticated user has insufficient permissions to delete the specified avatar.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user does not exist.

POST

Update the avatar for the user with the supplied slug.

This resource accepts POST multipart form data, containing a single image in a form-field named 'avatar'.

There are configurable server limits on both the dimensions (1024x1024 pixels by default) and uploaded file size (1MB by default). Several different image formats are supported, but PNG and JPEG are preferred due to the file size limit.

This resource has Cross-Site Request Forgery (XSRF) protection. To allow the request to pass the XSRF check the caller needs to send an X-Atlassian-Token HTTP header with the value no-check.

An example curl request to upload an image name 'avatar.png' would be:

 curl -X POST -u username:password -H "X-Atlassian-Token: no-check" http://example.com/rest/api/latest/users/jdoe/avatar.png -F avatar=@avatar.png
 

Users are always allowed to update their own avatar. To update someone else's avatar the authenticated user must have global ADMIN permission, or global SYS_ADMIN permission to update a SYS_ADMIN user's avatar.

Example response representations:

  • 201 [expand]

    The avatar was uploaded successfully.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user has insufficient permissions to update the avatar.

  • 404 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The specified user does not exist.

/rest/api/1.0/users/{userSlug}/settings

Rest resource for retrieving, and updating user settings key/values

Methods

POST

Update the entries of a map of user setting key/values for a specific user identified by the user slug.

Example request representations:

  • application/json [expand]

    Example
    {"string key":"string value","boolean key":true,"long key":10}

Example response representations:

  • 200 [expand]

    The {@link UserSettings were updated successfully}

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user is not a project administrator.

GET

Retrieve a map of user setting key values for a specific user identified by the user slug.

Example response representations:

  • 200 - application/json (settings) [expand]

    Example
    {"string key":"string value","boolean key":true,"long key":10}

    The user settings for the specified user slug.

  • 401 - application/json (errors) [expand]

    Example
    {"errors":[{"context":null,"message":"A detailed error message.","exceptionName":null}]}

    The currently authenticated user does not have permission to view the settings of this user.