REST Resources Provided By: Atlassian Stash REST Plugin

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

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

You can read more about developing Stash plugins in the Stash 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 Stash REST API.

Structure of the REST URIs

Stash'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 Stash REST API uses JSON as its communication format, and the standard HTTP methods like GET, PUT, POST and DELETE. URIs for Stash'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

Stash 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. The request to get a subsequent page should look like this:

    http://host:port/context/rest/api-name/api-version/path/to/resource?start={start of last page} + {size of last page}

For example:

    https://stash.atlassian.com/rest/api/1.0/projects/JIRA/repos/jira/commits?start=25

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.

Authentication

Any authentication that works against Stash will work against the REST API. The prefered 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 Stash 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 Stash 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

Stash 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, Stash 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

REST-ish endpoint for interacting with Stash

Resources

Resources

Rest resource for retrieving, creating and deleting users or groups

/rest/api/1.0/admin/groups

Methods

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

parameter	value	description
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 PROJECT_ADMIN permission or higher to call this resource.

request query parameters

parameter	value	description
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,
  "filter" : null
}

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 project administrator.

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

parameter	value	description
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.

/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 PROJECT_ADMIN permission to call this resource.

request query parameters

parameter	value	description
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",
    "directoryName" : "Stash Internal Directory",
    "mutableDetails" : true,
    "mutableGroups" : true
  } ],
  "start" : 0,
  "filter" : null
}

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 project administrator.

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",
  "directoryName" : "Stash Internal Directory",
  "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 deleted.

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

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

parameter	value	description
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

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.

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

parameter	value	description
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",
  "directoryName" : "Stash Internal Directory",
  "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.

/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 being deleted.

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

parameter	value	description
name	string

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 group being deleted.

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/add-user

Methods

POST

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

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/remove-user

Methods

POST

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 PROJECT_ADMIN permission to call this resource.

request query parameters

parameter value description

parameter	value	description
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

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",
    "directoryName" : "Stash Internal Directory",
    "mutableDetails" : true,
    "mutableGroups" : true
  } ],
  "start" : 0,
  "filter" : null
}

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 project administrator.

/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 PROJECT_ADMIN permission to call this resource.

request query parameters

parameter value description

parameter	value	description
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

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",
    "directoryName" : "Stash Internal Directory",
    "mutableDetails" : true,
    "mutableGroups" : true
  } ],
  "start" : 0,
  "filter" : null
}

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 project administrator.

/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 PROJECT_ADMIN permission to call this resource.

request query parameters

parameter value description

parameter	value	description
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

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,
  "filter" : null
}

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 project administrator.

/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 PROJECT_ADMIN permission to call this resource.

request query parameters

parameter value description

parameter	value	description
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

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,
  "filter" : null
}

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 project administrator.

/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

DELETE

Deletes the current mail server configuration.

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

Example response representations:

204 - application/json [expand]

The mail server 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/permissions/users

Methods

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 Stash 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

parameter	value	description
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

parameter	value	description
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.

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

parameter value description

parameter	value	description
filter	string Default:	if specified only user names containing the supplied string will be returned

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"
    },
    "permission" : "ADMIN"
  } ],
  "start" : 0,
  "filter" : null
}

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.

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

Methods

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

parameter	value	description
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.

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

parameter value description

parameter	value	description
filter	string Default:	if specified only group names containing the supplied string will be returned

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,
  "filter" : null
}

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 Stash 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

parameter	value	description
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.

/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

parameter value description

parameter	value	description
filter	string Default:	if specified only user names containing the supplied string will be returned

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"
  } ],
  "start" : 0,
  "filter" : null
}

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

parameter value description

parameter	value	description
filter	string Default:	if specified only group names containing the supplied string will be returned

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,
  "filter" : null
}

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/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 Stash"
}

The application properties.

/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 PROJECT_ADMIN permission or higher to call this resource.

request query parameters

parameter	value	description
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,
  "filter" : null
}

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

parameter	value	description
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

parameter	value	description
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/logs/logger/{loggerName}

resource-wide template parameters

parameter	value	description
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/logs/logger/{loggerName}/{levelName}

resource-wide template parameters

parameter	value	description
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 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/rootLogger/{levelName}

resource-wide template parameters

parameter	value	description
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/markup/preview

Methods

POST

Preview the generated html for given markdown contents.

Only authenticated users may call this resource.

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

parameter	value	description
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",
    "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",
      "isPersonal" : false,
      "link" : {
        "url" : "http://link/to/project",
        "rel" : "self"
      }
    },
    "public" : true,
    "cloneUrl" : "https://<baseURL>/scm/PRJ/my-repo.git",
    "link" : {
      "url" : "http://link/to/repository",
      "rel" : "self"
    }
  } ],
  "start" : 0,
  "filter" : null
}

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

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

parameter	value	description
name	string
permission	string

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",
    "isPersonal" : false,
    "link" : {
      "url" : "http://link/to/project",
      "rel" : "self"
    }
  } ],
  "start" : 0,
  "filter" : null
}

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.

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",
  "isPersonal" : false,
  "link" : {
    "url" : "http://link/to/project",
    "rel" : "self"
  }
}

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.

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

Methods

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",
  "isPersonal" : false,
  "link" : {
    "url" : "http://link/to/project",
    "rel" : "self"
  }
}

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.

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",
  "isPersonal" : false,
  "link" : {
    "url" : "http://link/to/project",
    "rel" : "self"
  }
}

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",
  "isPersonal" : false,
  "link" : {
    "url" : "http://link/to/project",
    "rel" : "self"
  }
}

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.

/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

parameter value description

parameter	value	description
s	int Default: `0`	The desired size of the image. The server will return an image as close as possible to the specified size.

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.

An example curl request to upload an image name 'avatar.png' would be:

 curl -X POST -u username:password 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/users

Methods

PUT

/rest/api/1.0/projects/{projectKey}/permissions/users?name&permission

Promote or demote a user's permission level for the specified project. Available project permissions are:

PROJECT_READ
PROJECT_WRITE
PROJECT_ADMIN

See the Stash documentation for a detailed explanation of what each permission entails.

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

parameter	value	description
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 project.
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 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

parameter	value	description
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 - 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 project.

404 - application/json (errors) [expand]

Example

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

The specified project 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.

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

parameter	value	description
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" : [ {
    "user" : {
      "name" : "jcitizen",
      "emailAddress" : "jane@example.com",
      "id" : 101,
      "displayName" : "Jane Citizen",
      "active" : true,
      "slug" : "jcitizen"
    },
    "permission" : "ADMIN"
  } ],
  "start" : 0,
  "filter" : null
}

A page of users and their highest permissions for the specified project.

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 for 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}/permissions/groups

Methods

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

parameter	value	description
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 - 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 project.

404 - application/json (errors) [expand]

Example

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

The specified project 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.

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

parameter	value	description
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,
  "filter" : null
}

A page of groups and their highest permissions for the specified project.

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 for 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.

PUT

/rest/api/1.0/projects/{projectKey}/permissions/groups?permission&name

Promote or demote a group's permission level for the specified project. Available project permissions are:

PROJECT_READ
PROJECT_WRITE
PROJECT_ADMIN

See the Stash documentation for a detailed explanation of what each permission entails.

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

parameter	value	description
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 project.
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 project or group does not exist.

/rest/api/1.0/projects/{projectKey}/permissions/{permission}/all

resource-wide template parameters

parameter	value	description
permission	string	the permission to grant

Methods

GET

Check whether the specified permission is the default permission (granted to all users) for a project. Available project permissions are:

PROJECT_READ
PROJECT_WRITE
PROJECT_ADMIN

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 - 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 of 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.

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. Available project permissions are:

PROJECT_READ
PROJECT_WRITE
PROJECT_ADMIN

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

request query parameters

parameter	value	description
allow	boolean	true to grant the specified permission to all users, or false to revoke it

Example response representations:

204 - application/json (permitted) [expand]
Example
```
{
  "permitted" : true
}
```
A simple entity indicating whether the specified permission is the default permission for this 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 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 of 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}/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

parameter	value	description
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,
  "filter" : null
}
```
A page of groups that have not been granted any permissions for the specified project.
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 for 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}/permissions/users/none

Methods

GET

/rest/api/1.0/projects/{projectKey}/permissions/users/none?filter

This is a paged API.
Retrieve a page of 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

parameter	value	description
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,
  "filter" : null
}
```
A page of users that have not been granted any permissions for the specified project.
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 for 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

resource-wide template parameters

parameter	value	description
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 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",
    "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",
      "isPersonal" : false,
      "link" : {
        "url" : "http://link/to/project",
        "rel" : "self"
      }
    },
    "public" : true,
    "cloneUrl" : "https://<baseURL>/scm/PRJ/my-repo.git",
    "link" : {
      "url" : "http://link/to/repository",
      "rel" : "self"
    }
  } ],
  "start" : 0,
  "filter" : null
}

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.

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
}

Example response representations:

201 - application/json (repository) [expand]

Example

{
  "slug" : "my-repo",
  "id" : 1,
  "name" : "My repo",
  "scmId" : "git",
  "state" : "AVAILABLE",
  "statusMessage" : "Available",
  "forkable" : true,
  "project" : {
    "key" : "PRJ",
    "id" : 1,
    "name" : "My Cool Project",
    "description" : "The description for my cool project.",
    "public" : true,
    "type" : "NORMAL",
    "isPersonal" : false,
    "link" : {
      "url" : "http://link/to/project",
      "rel" : "self"
    }
  },
  "public" : true,
  "cloneUrl" : "https://<baseURL>/scm/PRJ/my-repo.git",
  "link" : {
    "url" : "http://link/to/repository",
    "rel" : "self"
  }
}

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.

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

resource-wide template parameters

parameter	value	description
projectKey	string	the parent project key
repositorySlug	string	the repository slug
projectKey	string	the parent project key

Methods

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",
  "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",
    "isPersonal" : false,
    "link" : {
      "url" : "http://link/to/project",
      "rel" : "self"
    }
  },
  "public" : true,
  "cloneUrl" : "https://<baseURL>/scm/PRJ/my-repo.git",
  "link" : {
    "url" : "http://link/to/repository",
    "rel" : "self"
  }
}

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 name of a repository.

The repository's slug is derived from its name. If the name changes the slug may also change.

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"
}
```

Example response representations:

201 - application/json (repository) [expand]

Example

{
  "slug" : "my-repo",
  "id" : 1,
  "name" : "My repo",
  "scmId" : "git",
  "state" : "AVAILABLE",
  "statusMessage" : "Available",
  "forkable" : true,
  "project" : {
    "key" : "PRJ",
    "id" : 1,
    "name" : "My Cool Project",
    "description" : "The description for my cool project.",
    "public" : true,
    "type" : "NORMAL",
    "isPersonal" : false,
    "link" : {
      "url" : "http://link/to/project",
      "rel" : "self"
    }
  },
  "public" : true,
  "cloneUrl" : "https://<baseURL>/scm/PRJ/my-repo.git",
  "link" : {
    "url" : "http://link/to/repository",
    "rel" : "self"
  }
}

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

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 REPO_ADMIN permission for the specified repository to call this resource.

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 {@code POST} is not required to contain any properties. Even the name may be omitted. The following properties will be used, if provided:

{@code "name":"Fork name"} - Specifies the forked repository's name
- Defaults to the name of the origin repository if not specified
{@code "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"
  }
}

Example response representations:

201 - application/json (repository) [expand]

Example

{
  "slug" : "my-repo",
  "id" : 2,
  "name" : "My repo",
  "scmId" : "git",
  "state" : "AVAILABLE",
  "statusMessage" : "Available",
  "forkable" : true,
  "origin" : {
    "slug" : "my-repo",
    "id" : 1,
    "name" : "My repo",
    "scmId" : "git",
    "state" : "AVAILABLE",
    "statusMessage" : "Available",
    "forkable" : true,
    "project" : {
      "key" : "PRJ",
      "id" : 1,
      "name" : "My Cool Project",
      "description" : "The description for my cool project.",
      "public" : true,
      "type" : "NORMAL",
      "isPersonal" : false,
      "link" : {
        "url" : "http://link/to/project",
        "rel" : "self"
      }
    },
    "public" : true,
    "cloneUrl" : "https://<baseURL>/scm/PRJ/my-repo.git",
    "link" : {
      "url" : "http://link/to/repository",
      "rel" : "self"
    }
  },
  "project" : {
    "key" : "~JDOE",
    "id" : 2,
    "name" : "John Doe",
    "type" : "PERSONAL",
    "isPersonal" : true,
    "link" : {
      "url" : "http://link/to/project",
      "rel" : "self"
    }
  },
  "cloneUrl" : "https://<baseURL>/scm/JDOE/my-repo.git",
  "link" : {
    "url" : "http://link/to/repository",
    "rel" : "self"
  }
}

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.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/forks

resource-wide template parameters

parameter	value	description
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",
    "scmId" : "git",
    "state" : "AVAILABLE",
    "statusMessage" : "Available",
    "forkable" : true,
    "origin" : {
      "slug" : "my-repo",
      "id" : 1,
      "name" : "My repo",
      "scmId" : "git",
      "state" : "AVAILABLE",
      "statusMessage" : "Available",
      "forkable" : true,
      "project" : {
        "key" : "PRJ",
        "id" : 1,
        "name" : "My Cool Project",
        "description" : "The description for my cool project.",
        "public" : true,
        "type" : "NORMAL",
        "isPersonal" : false,
        "link" : {
          "url" : "http://link/to/project",
          "rel" : "self"
        }
      },
      "public" : true,
      "cloneUrl" : "https://<baseURL>/scm/PRJ/my-repo.git",
      "link" : {
        "url" : "http://link/to/repository",
        "rel" : "self"
      }
    },
    "project" : {
      "key" : "~JDOE",
      "id" : 2,
      "name" : "John Doe",
      "type" : "PERSONAL",
      "isPersonal" : true,
      "link" : {
        "url" : "http://link/to/project",
        "rel" : "self"
      }
    },
    "cloneUrl" : "https://<baseURL>/scm/JDOE/my-repo.git",
    "link" : {
      "url" : "http://link/to/repository",
      "rel" : "self"
    }
  } ],
  "start" : 0,
  "filter" : null
}

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

resource-wide template parameters

parameter	value	description
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",
  "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",
    "isPersonal" : false,
    "link" : {
      "url" : "http://link/to/project",
      "rel" : "self"
    }
  },
  "public" : true,
  "cloneUrl" : "https://<baseURL>/scm/PRJ/my-repo.git",
  "link" : {
    "url" : "http://link/to/repository",
    "rel" : "self"
  }
}

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

parameter	value	description
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",
    "scmId" : "git",
    "state" : "AVAILABLE",
    "statusMessage" : "Available",
    "forkable" : true,
    "origin" : {
      "slug" : "my-repo",
      "id" : 1,
      "name" : "My repo",
      "scmId" : "git",
      "state" : "AVAILABLE",
      "statusMessage" : "Available",
      "forkable" : true,
      "project" : {
        "key" : "PRJ",
        "id" : 1,
        "name" : "My Cool Project",
        "description" : "The description for my cool project.",
        "public" : true,
        "type" : "NORMAL",
        "isPersonal" : false,
        "link" : {
          "url" : "http://link/to/project",
          "rel" : "self"
        }
      },
      "public" : true,
      "cloneUrl" : "https://<baseURL>/scm/PRJ/my-repo.git",
      "link" : {
        "url" : "http://link/to/repository",
        "rel" : "self"
      }
    },
    "project" : {
      "key" : "~JDOE",
      "id" : 2,
      "name" : "John Doe",
      "type" : "PERSONAL",
      "isPersonal" : true,
      "link" : {
        "url" : "http://link/to/project",
        "rel" : "self"
      }
    },
    "cloneUrl" : "https://<baseURL>/scm/JDOE/my-repo.git",
    "link" : {
      "url" : "http://link/to/repository",
      "rel" : "self"
    }
  } ],
  "start" : 0,
  "filter" : null
}

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

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/branches?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 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

parameter	value	description
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" : "refs/heads/master",
    "displayId" : "master",
    "latestChangeset" : "8d51122def5632836d1cb1026e879069e10a1e13",
    "isDefault" : true
  } ],
  "start" : 0,
  "filter" : null
}

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.

/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.
Get the default branch of the repository.

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/master",
  "displayId" : "master",
  "latestChangeset" : "8d51122def5632836d1cb1026e879069e10a1e13",
  "isDefault" : true
}

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 or the repository has no default branch configured.

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/master"
}
```

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&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.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters

parameter	value	description
at	string Default:	the changeset id or ref to retrieve the content for.
type	boolean Default: `false`	if true only the type will be returned for the file path instead of the contents.
blame	string	if present the blame will be returned for the file as well.
noContent	string	if present and used with blame 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,
  "filter" : null,
  "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

parameter value description

parameter	value	description
path	string Default:	the file path to retrieve content from

path

string

Default:

the file path to retrieve content from

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/browse/{path:.*}?at&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.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters

parameter	value	description
at	string Default:	the changeset id or ref to retrieve the content for.
type	boolean Default: `false`	if true only the type will be returned for the file path instead of the contents.
blame	string	if present the blame will be returned for the file as well.
noContent	string	if present and used with blame 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,
  "filter" : null,
  "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.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters

parameter	value	description
since	string	the changeset to which `until` should be compared to produce a page of changes. If not specified the parent of the until changeset is used.
until	string	the changeset to retrieve file changes for.

Example response representations:

200 - application/json (page) [expand]

Example

{
  "size" : 1,
  "limit" : 25,
  "isLastPage" : true,
  "values" : [ {
    "contentId" : "abcdef0123abcdef4567abcdef8987abcdef6543",
    "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,
    "link" : {
      "url" : "http://link/to/restchange",
      "rel" : "self"
    }
  } ],
  "start" : 0,
  "filter" : null
}

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?path&since&until&withCounts

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 changesets from a given starting commit or between two commits. The commits may be identified by branch or tag name or by hash. A path may be supplied to restrict the returned changesets 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

parameter	value	description
path	string	an optional path to filter changesets by
since	string	the changeset id or ref (exclusively) to restrieve changesets after
until	string	the changeset id or ref (inclusively) to retrieve changesets before
withCounts	boolean Default: `false`	optionally include the total number of changesets and total number of unique authors

Example response representations:

200 - application/json (page) [expand]

Example

{
  "size" : 1,
  "limit" : 25,
  "isLastPage" : true,
  "values" : [ {
    "id" : "def0123abcdef4567abcdef8987abcdef6543abc",
    "displayId" : "def0123",
    "author" : {
      "name" : "charlie",
      "emailAddress" : "charlie@example.com"
    },
    "authorTimestamp" : 1374798803452,
    "message" : "More work on feature 1",
    "parents" : [ {
      "id" : "abcdef0123abcdef4567abcdef8987abcdef6543",
      "displayId" : "abcdef0"
    } ]
  } ],
  "start" : 0,
  "filter" : null,
  "authorCount" : 1,
  "totalCount" : 1
}

A page of changesets.

400 - application/json (errors) [expand]

Example

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

One of the supplied changeset 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/{changesetId:.*}

resource-wide template parameters

parameter	value	description
changesetId	string	the changeset id or ref (inclusively) to retrieve changesets before.

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/commits/{changesetId:.*}?path

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.
Retrieve a changeset for a given changeset id, tag or branch.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters

parameter	value	description
path	string	an optional path to filter changesets 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 (changeset) [expand]

Example

{
  "id" : "abcdef0123abcdef4567abcdef8987abcdef6543",
  "displayId" : "abcdef0",
  "author" : {
    "name" : "charlie",
    "emailAddress" : "charlie@example.com"
  },
  "authorTimestamp" : 1374798803452,
  "message" : "WIP on feature 1",
  "parents" : [ {
    "id" : "abcdef0123abcdef4567abcdef8987abcdef6543",
    "displayId" : "abcdef0"
  } ]
}

A changeset.

400 - application/json (errors) [expand]

Example

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

The supplied changeset ids or ref 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}/diff/{path:.*}

resource-wide template parameters

parameter	value	description
path	string	the path to the file which should be diffed.

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/diff/{path:.*}?since&until&srcPath&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

parameter	value	description
since	string	the base revision to diff from. If omitted the parent revision of the until revision is used.
until	string	the target revision to diff to.
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 - 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" : false
  } ]
}

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

parameter value description

string

Default:

the changeset 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,
  "filter" : null
}

A page of files.

400 - application/json (errors) [expand]
Example
```
{
  "errors" : [ {
    "context" : null,
    "message" : "A detailed error message.",
    "exceptionName" : null
  } ]
}
```
The path supplied is not a directory at the supplied changeset.
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 supplied does not exist at the supplied changeset.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/files/{path:.*}

resource-wide template parameters

parameter value description

path

string

Default:

the directory to list files for.

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/files/{path:.*}?at

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

request query parameters

parameter	value	description
at	string	the changeset 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,
  "filter" : null
}

A page of files.

400 - application/json (errors) [expand]
Example
```
{
  "errors" : [ {
    "context" : null,
    "message" : "A detailed error message.",
    "exceptionName" : null
  } ]
}
```
The path supplied is not a directory at the supplied changeset.
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 supplied does not exist at the supplied changeset.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/groups

Methods

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 Stash 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

parameter	value	description
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.

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

parameter	value	description
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.

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

parameter	value	description
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,
  "filter" : null
}

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.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/permissions/users

Methods

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 Stash 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

parameter	value	description
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.

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

parameter	value	description
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.

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

parameter	value	description
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" : [ {
    "user" : {
      "name" : "jcitizen",
      "emailAddress" : "jane@example.com",
      "id" : 101,
      "displayName" : "Jane Citizen",
      "active" : true,
      "slug" : "jcitizen"
    },
    "permission" : "ADMIN"
  } ],
  "start" : 0,
  "filter" : null
}

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.

/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

parameter	value	description
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,
  "filter" : null
}
```
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/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 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

parameter	value	description
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,
  "filter" : null
}
```
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

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.
Create a new pull request between two branches. The branches may be in the same repository, or different ones. When using different repositories, they must still be in the same {@link Repository#getHierarchyId() hierarchy}.

The authenticated user must have REPO_READ permission for the "from" and "to"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",
  "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"
      }
    }
  },
  "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",
  "createdDate" : 1359075920,
  "updatedDate" : 1359075920,
  "fromRef" : {
    "id" : "refs/heads/feature",
    "displayId" : "feature-ABC-123",
    "latestChangeset" : "babecafebabecafebabecafebabecafebabecafe",
    "repository" : {
      "slug" : "my-repo",
      "id" : 1,
      "name" : "My repo",
      "scmId" : "git",
      "state" : "AVAILABLE",
      "statusMessage" : "Available",
      "forkable" : true,
      "project" : {
        "key" : "PRJ",
        "id" : 1,
        "name" : "My Cool Project",
        "description" : "The description for my cool project.",
        "public" : true,
        "type" : "NORMAL",
        "isPersonal" : false,
        "link" : {
          "url" : "http://link/to/project",
          "rel" : "self"
        }
      },
      "public" : true,
      "cloneUrl" : "https://<baseURL>/scm/PRJ/my-repo.git",
      "link" : {
        "url" : "http://link/to/repository",
        "rel" : "self"
      }
    }
  },
  "toRef" : {
    "id" : "refs/heads/master",
    "displayId" : "master",
    "latestChangeset" : "cafebabecafebabecafebabecafebabecafebabe",
    "repository" : {
      "slug" : "my-repo",
      "id" : 1,
      "name" : "My repo",
      "scmId" : "git",
      "state" : "AVAILABLE",
      "statusMessage" : "Available",
      "forkable" : true,
      "project" : {
        "key" : "PRJ",
        "id" : 1,
        "name" : "My Cool Project",
        "description" : "The description for my cool project.",
        "public" : true,
        "type" : "NORMAL",
        "isPersonal" : false,
        "link" : {
          "url" : "http://link/to/project",
          "rel" : "self"
        }
      },
      "public" : true,
      "cloneUrl" : "https://<baseURL>/scm/PRJ/my-repo.git",
      "link" : {
        "url" : "http://link/to/repository",
        "rel" : "self"
      }
    }
  },
  "author" : {
    "user" : {
      "name" : "alice",
      "emailAddress" : "alice@example.com",
      "id" : 92903040,
      "displayName" : "Alice",
      "active" : true,
      "slug" : "alice"
    },
    "role" : "PARTICIPANT",
    "approved" : false
  },
  "reviewers" : [ {
    "user" : {
      "name" : "jcitizen",
      "emailAddress" : "jane@example.com",
      "id" : 101,
      "displayName" : "Jane Citizen",
      "active" : true,
      "slug" : "jcitizen"
    },
    "role" : "REVIEWER",
    "approved" : false
  } ],
  "participants" : [ ],
  "link" : {
    "url" : "http://link/to/pullrequest",
    "rel" : "self"
  }
}

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.

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests?direction&at&state&order

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.

request query parameters

parameter	value	description
direction	string Default: `incoming`	(optional, defaults to INCOMING) the direction relative to the specified repository. Either INCOMING or OUTGOING.
at	string	(optional) a specific branch to find pull requests to or from.
state	string	(optional, defaults to OPEN) only pull requests in the specified state will be returned. Either OPEN, DECLINED or MERGED.
order	string	(optional) the order to return pull requests in, either OLDEST (as in: "oldest first") or NEWEST.

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",
    "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"
        }
      }
    },
    "author" : {
      "user" : {
        "name" : "tom",
        "emailAddress" : "tom@example.com",
        "id" : 115026,
        "displayName" : "Tom",
        "active" : true,
        "slug" : "tom"
      },
      "role" : "AUTHOR",
      "approved" : true
    },
    "reviewers" : [ {
      "user" : {
        "name" : "jcitizen",
        "emailAddress" : "jane@example.com",
        "id" : 101,
        "displayName" : "Jane Citizen",
        "active" : true,
        "slug" : "jcitizen"
      },
      "role" : "REVIEWER",
      "approved" : true
    } ],
    "participants" : [ {
      "user" : {
        "name" : "harry",
        "emailAddress" : "harry@example.com",
        "id" : 99049120,
        "displayName" : "Harry",
        "active" : true,
        "slug" : "harry"
      },
      "role" : "PARTICIPANT",
      "approved" : true
    }, {
      "user" : {
        "name" : "dick",
        "emailAddress" : "dick@example.com",
        "id" : 3083181,
        "displayName" : "Dick",
        "active" : true,
        "slug" : "dick"
      },
      "role" : "PARTICIPANT",
      "approved" : false
    } ],
    "link" : {
      "url" : "http://link/to/pullrequest",
      "rel" : "self"
    }
  } ],
  "start" : 0,
  "filter" : null
}

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.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}

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",
  "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"
      }
    }
  },
  "author" : {
    "user" : {
      "name" : "tom",
      "emailAddress" : "tom@example.com",
      "id" : 115026,
      "displayName" : "Tom",
      "active" : true,
      "slug" : "tom"
    },
    "role" : "AUTHOR",
    "approved" : true
  },
  "reviewers" : [ {
    "user" : {
      "name" : "jcitizen",
      "emailAddress" : "jane@example.com",
      "id" : 101,
      "displayName" : "Jane Citizen",
      "active" : true,
      "slug" : "jcitizen"
    },
    "role" : "REVIEWER",
    "approved" : true
  } ],
  "participants" : [ {
    "user" : {
      "name" : "harry",
      "emailAddress" : "harry@example.com",
      "id" : 99049120,
      "displayName" : "Harry",
      "active" : true,
      "slug" : "harry"
    },
    "role" : "PARTICIPANT",
    "approved" : true
  }, {
    "user" : {
      "name" : "dick",
      "emailAddress" : "dick@example.com",
      "id" : 3083181,
      "displayName" : "Dick",
      "active" : true,
      "slug" : "dick"
    },
    "role" : "PARTICIPANT",
    "approved" : false
  } ],
  "link" : {
    "url" : "http://link/to/pullrequest",
    "rel" : "self"
  }
}

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",
  "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"
      }
    }
  },
  "author" : {
    "user" : {
      "name" : "tom",
      "emailAddress" : "tom@example.com",
      "id" : 115026,
      "displayName" : "Tom",
      "active" : true,
      "slug" : "tom"
    },
    "role" : "AUTHOR",
    "approved" : true
  },
  "reviewers" : [ {
    "user" : {
      "name" : "jcitizen",
      "emailAddress" : "jane@example.com",
      "id" : 101,
      "displayName" : "Jane Citizen",
      "active" : true,
      "slug" : "jcitizen"
    },
    "role" : "REVIEWER",
    "approved" : true
  } ],
  "participants" : [ {
    "user" : {
      "name" : "harry",
      "emailAddress" : "harry@example.com",
      "id" : 99049120,
      "displayName" : "Harry",
      "active" : true,
      "slug" : "harry"
    },
    "role" : "PARTICIPANT",
    "approved" : true
  }, {
    "user" : {
      "name" : "dick",
      "emailAddress" : "dick@example.com",
      "id" : 3083181,
      "displayName" : "Dick",
      "active" : true,
      "slug" : "dick"
    },
    "role" : "PARTICIPANT",
    "approved" : false
  } ],
  "link" : {
    "url" : "http://link/to/pullrequest",
    "rel" : "self"
  }
}

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

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/activities

resource-wide template parameters

parameter	value	description
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

parameter	value	description
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"
    },
    "action" : "COMMENTED",
    "commentAction" : "ADDED",
    "comment" : {
      "id" : 1,
      "version" : 1,
      "text" : "A measured reply.",
      "author" : {
        "name" : "jcitizen",
        "emailAddress" : "jane@example.com",
        "id" : 101,
        "displayName" : "Jane Citizen",
        "active" : true,
        "slug" : "jcitizen"
      },
      "createdDate" : 1374798803283,
      "updatedDate" : 1374798803283,
      "comments" : [ {
        "id" : 1,
        "version" : 1,
        "text" : "An insightful comment.",
        "author" : {
          "name" : "jcitizen",
          "emailAddress" : "jane@example.com",
          "id" : 101,
          "displayName" : "Jane Citizen",
          "active" : true,
          "slug" : "jcitizen"
        },
        "createdDate" : 1374798803283,
        "updatedDate" : 1374798803283,
        "comments" : [ ],
        "permittedOperations" : {
          "editable" : true,
          "deletable" : true
        }
      } ],
      "permittedOperations" : {
        "editable" : true,
        "deletable" : true
      }
    }
  }, {
    "id" : 101,
    "createdDate" : 1359065920,
    "user" : {
      "name" : "jcitizen",
      "emailAddress" : "jane@example.com",
      "id" : 101,
      "displayName" : "Jane Citizen",
      "active" : true,
      "slug" : "jcitizen"
    },
    "action" : "RESCOPED",
    "fromHash" : "abcdeabcdeabcdeabcdeabcdeabcdeabcdeabcde",
    "previousFromHash" : "bcdeabcdeabcdeabcdeabcdeabcdeabcdeabcdea",
    "previousToHash" : "cdeabcdeabcdeabcdeabcdeabcdeabcdeabcdeab",
    "toHash" : "ddeabcdeabcdeabcdeabcdeabcdeabcdeabcdeabc",
    "added" : {
      "changesets" : [ {
        "id" : "abcdef0123abcdef4567abcdef8987abcdef6543",
        "displayId" : "abcdef0",
        "author" : {
          "name" : "charlie",
          "emailAddress" : "charlie@example.com"
        },
        "authorTimestamp" : 1374798803452,
        "message" : "WIP on feature 1",
        "parents" : [ {
          "id" : "abcdef0123abcdef4567abcdef8987abcdef6543",
          "displayId" : "abcdef0"
        } ]
      } ],
      "total" : 1
    },
    "removed" : {
      "changesets" : [ {
        "id" : "def0123abcdef4567abcdef8987abcdef6543abc",
        "displayId" : "def0123",
        "author" : {
          "name" : "charlie",
          "emailAddress" : "charlie@example.com"
        },
        "authorTimestamp" : 1374798803452,
        "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"
    },
    "action" : "MERGED"
  } ],
  "start" : 0,
  "filter" : null
}

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

parameter	value	description
pullRequestId	long

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

parameter value description

version

int

Default: -1

the current version of the pull request. If the server's version is newer than 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

parameter	value	description
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" : false,
  "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 merge status of a 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

parameter value description

version

int

Default: -1

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",
  "createdDate" : 1359075920,
  "updatedDate" : 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"
      }
    }
  },
  "author" : {
    "user" : {
      "name" : "tom",
      "emailAddress" : "tom@example.com",
      "id" : 115026,
      "displayName" : "Tom",
      "active" : true,
      "slug" : "tom"
    },
    "role" : "AUTHOR",
    "approved" : true
  },
  "reviewers" : [ {
    "user" : {
      "name" : "jcitizen",
      "emailAddress" : "jane@example.com",
      "id" : 101,
      "displayName" : "Jane Citizen",
      "active" : true,
      "slug" : "jcitizen"
    },
    "role" : "REVIEWER",
    "approved" : true
  } ],
  "participants" : [ {
    "user" : {
      "name" : "harry",
      "emailAddress" : "harry@example.com",
      "id" : 99049120,
      "displayName" : "Harry",
      "active" : true,
      "slug" : "harry"
    },
    "role" : "PARTICIPANT",
    "approved" : true
  }, {
    "user" : {
      "name" : "dick",
      "emailAddress" : "dick@example.com",
      "id" : 3083181,
      "displayName" : "Dick",
      "active" : true,
      "slug" : "dick"
    },
    "role" : "PARTICIPANT",
    "approved" : true
  } ],
  "link" : {
    "url" : "http://link/to/pullrequest",
    "rel" : "self"
  }
}

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

parameter	value	description
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

parameter value description

version

int

Default: -1

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",
  "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"
      }
    }
  },
  "author" : {
    "user" : {
      "name" : "tom",
      "emailAddress" : "tom@example.com",
      "id" : 115026,
      "displayName" : "Tom",
      "active" : true,
      "slug" : "tom"
    },
    "role" : "AUTHOR",
    "approved" : true
  },
  "reviewers" : [ {
    "user" : {
      "name" : "jcitizen",
      "emailAddress" : "jane@example.com",
      "id" : 101,
      "displayName" : "Jane Citizen",
      "active" : true,
      "slug" : "jcitizen"
    },
    "role" : "REVIEWER",
    "approved" : true
  } ],
  "participants" : [ {
    "user" : {
      "name" : "harry",
      "emailAddress" : "harry@example.com",
      "id" : 99049120,
      "displayName" : "Harry",
      "active" : true,
      "slug" : "harry"
    },
    "role" : "PARTICIPANT",
    "approved" : true
  }, {
    "user" : {
      "name" : "dick",
      "emailAddress" : "dick@example.com",
      "id" : 3083181,
      "displayName" : "Dick",
      "active" : true,
      "slug" : "dick"
    },
    "role" : "PARTICIPANT",
    "approved" : false
  } ],
  "link" : {
    "url" : "http://link/to/pullrequest",
    "rel" : "self"
  }
}

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

parameter	value	description
pullRequestId	long	the id of the pull request within the repository

Methods

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.

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"
  },
  "role" : "REVIEWER",
  "approved" : true
}

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.

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.

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"
  },
  "role" : "REVIEWER",
  "approved" : false
}

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.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/changes

Methods

GET

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.

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.

Example response representations:

200 - application/json (page) [expand]

Example

{
  "size" : 1,
  "limit" : 25,
  "isLastPage" : true,
  "values" : [ {
    "contentId" : "abcdef0123abcdef4567abcdef8987abcdef6543",
    "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,
    "link" : {
      "url" : "http://link/to/restchange",
      "rel" : "self"
    }
  } ],
  "start" : 0,
  "filter" : null
}

A page of Changes 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

resource-wide template parameters

parameter	value	description
pullRequestId	long	the id of the pull request within the repository

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": {
            "path": "path/to/file",
            "srcPath": "path/to/file"
         }
     }

File line comment:

     {
         "text": "A pithy comment on a particular line within a file.",
         "anchor": {
             "line": 1,
             "lineType": "CONTEXT",
             "path": "path/to/file",
             "srcPath": "path/to/file"
         }
     }

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).

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.

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
  },
  "anchor" : {
    "line" : 1,
    "lineType" : "CONTEXT",
    "path" : "path/to/file",
    "srcPath" : "path/to/file"
  }
}

Example response representations:

201 - application/json (comment) [expand]

Example

{
  "id" : 1,
  "version" : 1,
  "text" : "A measured reply.",
  "author" : {
    "name" : "jcitizen",
    "emailAddress" : "jane@example.com",
    "id" : 101,
    "displayName" : "Jane Citizen",
    "active" : true,
    "slug" : "jcitizen"
  },
  "createdDate" : 1374798803283,
  "updatedDate" : 1374798803283,
  "comments" : [ {
    "id" : 1,
    "version" : 1,
    "text" : "An insightful comment.",
    "author" : {
      "name" : "jcitizen",
      "emailAddress" : "jane@example.com",
      "id" : 101,
      "displayName" : "Jane Citizen",
      "active" : true,
      "slug" : "jcitizen"
    },
    "createdDate" : 1374798803283,
    "updatedDate" : 1374798803283,
    "comments" : [ ],
    "permittedOperations" : {
      "editable" : true,
      "deletable" : true
    }
  } ],
  "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

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/comments/{commentId}

resource-wide template parameters

parameter	value	description
pullRequestId	long	the id of the pull request within the repository
pullRequestId	long	the id of the pull request within the repository
commentId	long	the id of the comment to update

Methods

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

{
  "id" : 1,
  "version" : 1,
  "text" : "A measured reply.",
  "author" : {
    "name" : "jcitizen",
    "emailAddress" : "jane@example.com",
    "id" : 101,
    "displayName" : "Jane Citizen",
    "active" : true,
    "slug" : "jcitizen"
  },
  "createdDate" : 1374798803283,
  "updatedDate" : 1374798803283,
  "comments" : [ {
    "id" : 1,
    "version" : 1,
    "text" : "An insightful comment.",
    "author" : {
      "name" : "jcitizen",
      "emailAddress" : "jane@example.com",
      "id" : 101,
      "displayName" : "Jane Citizen",
      "active" : true,
      "slug" : "jcitizen"
    },
    "createdDate" : 1374798803283,
    "updatedDate" : 1374798803283,
    "comments" : [ ],
    "permittedOperations" : {
      "editable" : true,
      "deletable" : true
    }
  } ],
  "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

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

parameter value description

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 the text of a comment. Only the user who created a comment may update it.

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 this pull request targets to call this resource.

Example request representations:

application/json [expand]

Example

{
  "version" : 0,
  "text" : "A pithy comment."
}

Example response representations:

201 - application/json (comment) [expand]

Example

{
  "id" : 1,
  "version" : 1,
  "text" : "A measured reply.",
  "author" : {
    "name" : "jcitizen",
    "emailAddress" : "jane@example.com",
    "id" : 101,
    "displayName" : "Jane Citizen",
    "active" : true,
    "slug" : "jcitizen"
  },
  "createdDate" : 1374798803283,
  "updatedDate" : 1374798803283,
  "comments" : [ {
    "id" : 1,
    "version" : 1,
    "text" : "An insightful comment.",
    "author" : {
      "name" : "jcitizen",
      "emailAddress" : "jane@example.com",
      "id" : 101,
      "displayName" : "Jane Citizen",
      "active" : true,
      "slug" : "jcitizen"
    },
    "createdDate" : 1374798803283,
    "updatedDate" : 1374798803283,
    "comments" : [ ],
    "permittedOperations" : {
      "editable" : true,
      "deletable" : true
    }
  } ],
  "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.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/commits

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/commits?withCounts

This is a paged API. This API can also be invoked via a user-centric URL when addressing repositories in personal projects.
Retrieve changesets 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

parameter	value	description
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 changesets.

Example response representations:

200 - application/json (page) [expand]

Example

{
  "size" : 1,
  "limit" : 25,
  "isLastPage" : true,
  "values" : [ {
    "id" : "def0123abcdef4567abcdef8987abcdef6543abc",
    "displayId" : "def0123",
    "author" : {
      "name" : "charlie",
      "emailAddress" : "charlie@example.com"
    },
    "authorTimestamp" : 1374798803452,
    "message" : "More work on feature 1",
    "parents" : [ {
      "id" : "abcdef0123abcdef4567abcdef8987abcdef6543",
      "displayId" : "abcdef0"
    } ]
  } ],
  "start" : 0,
  "filter" : null,
  "authorCount" : 1,
  "totalCount" : 1
}

a page of changesets 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?srcPath&whitespace

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.
Streams a diff for the specified path within a pull request. If the 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

parameter	value	description
srcPath	string	the previous path to the file, if the file has been copied, moved or renamed
whitespace	string	optional whitespace flag which can be set to `ignore-all`

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" : [ {
      "id" : 1,
      "version" : 1,
      "text" : "An insightful comment.",
      "author" : {
        "name" : "jcitizen",
        "emailAddress" : "jane@example.com",
        "id" : 101,
        "displayName" : "Jane Citizen",
        "active" : true,
        "slug" : "jcitizen"
      },
      "createdDate" : 1374798803283,
      "updatedDate" : 1374798803283,
      "comments" : [ ],
      "permittedOperations" : {
        "editable" : true,
        "deletable" : true
      }
    } ],
    "truncated" : false
  } ]
}

a page of differences from a pull request, for the specified path.

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 no path was specified or the request was otherwise 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

parameter	value	description
path	string	the path to the file which should be diffed

Methods

GET

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/diff/{path:.*}?srcPath&whitespace

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

parameter	value	description
srcPath	string	the previous path to the file, if the file has been copied, moved or renamed
whitespace	string	optional whitespace flag which can be set to `ignore-all`

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" : [ {
      "id" : 1,
      "version" : 1,
      "text" : "An insightful comment.",
      "author" : {
        "name" : "jcitizen",
        "emailAddress" : "jane@example.com",
        "id" : 101,
        "displayName" : "Jane Citizen",
        "active" : true,
        "slug" : "jcitizen"
      },
      "createdDate" : 1374798803283,
      "updatedDate" : 1374798803283,
      "comments" : [ ],
      "permittedOperations" : {
        "editable" : true,
        "deletable" : true
      }
    } ],
    "truncated" : false
  } ]
}

a page of differences from a pull request, for the specified path.

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 no path was specified or the request was otherwise 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

parameter	value	description
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"
    },
    "role" : "REVIEWER",
    "approved" : true
  } ],
  "start" : 0,
  "filter" : null
}

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.

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"
  },
  "role" : "REVIEWER",
  "approved" : false
}

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.

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.

request query parameters

parameter	value	description
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.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/pull-requests/{pullRequestId}/watch

resource-wide template parameters

parameter	value	description
pullRequestId	long	the id of the pull request within the repository

Methods

POST

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.
Make the authenticated user watch 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.

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.
Make the authenticated user stop watching 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.

/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_ADMIN permission for the specified repository to call this resource.

request query parameters

parameter value description

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
    },
    "enabled" : true,
    "configured" : true
  } ],
  "start" : 0,
  "filter" : null
}

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 or repository does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}

resource-wide template parameters

parameter	value	description
hookKey	string

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 repositories.

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
  },
  "enabled" : true,
  "configured" : true
}

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 project, repository or hook does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}/enabled

resource-wide template parameters

parameter	value	description
hookKey	string

Methods

DELETE

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.
Disable a repository hook for this repositories.

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
  },
  "enabled" : true,
  "configured" : true
}

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, repository or hook does not exist.

PUT

This API can also be invoked via a user-centric URL when addressing repositories in personal projects.
Enable a repository hook for this repositories and optionally applying new configuration.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

request header parameters

parameter value description

Content-Length

int

Default: 0

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
  },
  "enabled" : true,
  "configured" : true
}

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, repository or hook does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/settings/hooks/{hookKey}/settings

resource-wide template parameters

parameter	value	description
hookKey	string

Methods

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 repositories.

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
  },
  "enabled" : true,
  "configured" : true
}

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, repository or hook does not exist.

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 repositories.

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.

Example request representations:

application/json [expand]

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
  },
  "enabled" : true,
  "configured" : true
}

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, repository or hook does not exist.

/rest/api/1.0/projects/{projectKey}/repos/{repositorySlug}/tags

Methods

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

parameter	value	description
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",
    "latestChangeset" : "8d351a10fb428c0c1239530256e21cf24f136e73",
    "hash" : "8d51122def5632836d1cb1026e879069e10a1e13"
  } ],
  "start" : 0,
  "filter" : null
}

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

REST resource for searching through repositories

Methods

GET

/rest/api/1.0/repos?name&projectname&permission&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 {@code 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

parameter	value	description
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`.
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",
    "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",
      "isPersonal" : false,
      "link" : {
        "url" : "http://link/to/project",
        "rel" : "self"
      }
    },
    "public" : true,
    "cloneUrl" : "https://<baseURL>/scm/PRJ/my-repo.git",
    "link" : {
      "url" : "http://link/to/repository",
      "rel" : "self"
    }
  } ],
  "start" : 0,
  "filter" : null
}

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/users

Methods

GET

/rest/api/1.0/users?filter

This is a paged API.
Retrieve a page of users.

Only authenticated users may call this resource.

request query parameters

parameter	value	description
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" : "jcitizen",
    "emailAddress" : "jane@example.com",
    "id" : 101,
    "displayName" : "Jane Citizen",
    "active" : true,
    "slug" : "jcitizen"
  } ],
  "start" : 0,
  "filter" : null
}

A page of users.

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. Note that the name attribute is ignored, the update will always be applied to the currently authenticated user.

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

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"
}
```
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.