Welcome to the Project Portfolio Management REST API reference.
Looking for the REST API reference for a Jira version? Follow the links below.
If you haven't integrated with Jira Server before, read the Getting started guide in the Jira Server developer documentation. You may also want to read our Jira REST API overview, which describes how the Jira REST APIs work, including a simple example of a REST call.
POST to the
Jira'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 Jira REST API uses JSON as its communication format, and the standard HTTP methods like
DELETE (see API descriptions below for which methods are available for each resource). URIs for Jira's REST API resource have the following structure:
Currently there are two API names available, which will be discussed further below:
auth- for authentication-related operations, and
api- for everything else.
The current API version is
2. However, there is also a symbolic version, called
latest, which resolves to the latest version supported by the given Jira instance. As an example, if you wanted to retrieve the JSON representation of issue JRA-9 from Atlassian's public issue tracker, you would access:
In order to simplify API responses, the Jira REST API uses resource expansion. This means the API will only return parts of the resource when explicitly requested.
You can use the
expand query parameter to specify a comma-separated list of entities that you want expanded, identifying each of them by name. For example, appending
?expand=names,renderedFields to an issue's URI requests the inclusion of the translated field names and the HTML-rendered field values in the response. Continuing with our example above, we would use the following URL to get that information for JRA-9:
To discover the identifiers for each entity, look at the
expand property in the parent object. In the JSON example below, the resource declares widgets as being expandable.
You can use the dot notation to specify expansion of entities within another entity. For example
?expand=widgets.fringels would expand the widgets collection and also the fringel property on each widget.
Jira uses pagination to limit the response size for resources that return a potentially large collection of items. A request to a paged API will result in a values array wrapped in a JSON object with some paging metadata, for example:
Clients can use the "startAt" and "maxResults" parameters to retrieve the desired numbers of results.
The "maxResults" parameter indicates how many results to return per page. Each API may have a different limit for number of items returned.
The "startAt" parameter indicates which item should be used as the first item in the page of results.
Important: The response contains a "total" field which denotes the total number of entities contained in all pages. This number may change as the client requests the subsequent pages. A client should always assume that the requested page can be empty. REST API consumers should also consider the field to be optional. In cases, when calculating this value is too expensive we may not include this in response.
Some resources support ordering by a specific field. Ordering request is provided in the orderBy query parameter. See the docs for specific methods to see which fields they support and if they support ordering at all.
Ordering can be ascending or descending. By default it's ascending. To specify the ordering use "-" or "+" sign. Examples:
Order by "name" ascending
Order by "name" ascending
Order by "name" descending
Methods marked as experimental may change without an earlier notice. We are looking for your feedback for these methods.
Special request and response headers
- X-AUSERNAME - Response header which contains either username of the authenticated user or 'anonymous'.
- X-Atlassian-Token - methods which accept multipart/form-data will only process requests with 'X-Atlassian-Token: no-check' header.
Most resources will return a response body in addition to the status code. Usually, the JSON schema of the entity returned is the following: