Welcome to the Project Portfolio Management REST API reference.

Looking for the REST API reference for a Jira version? Follow the links below.

Getting started

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.

Authentication

The preferred authentication methods for the Jira REST APIs are OAuth and HTTP basic authentication (when using SSL).

Jira itself uses cookie-based authentication in the browser, so you can call REST from JavaScript on the page and rely on the authentication that the browser has established. To reproduce the behavior of the Jira log-in page (for example, to display authentication error messages to users) can POST to the /auth/1/session resource.

URI Structure

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 GET, PUT, POST and DELETE (see API descriptions below for which methods are available for each resource). URIs for Jira's REST API resource have the following structure:

http://host:port/context/rest/api-name/api-version/resource-name

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:

https://jira.atlassian.com/rest/api/latest/issue/JRA-9

There is a WADL document that contains the documentation for each resource in the Jira REST API. It is available here.

Expansion

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:

https://jira.atlassian.com/rest/api/latest/issue/JRA-9?expand=names,renderedFields

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.

{
    "expand": "widgets",
    "self": "http://www.example.com/jira/rest/api/resource/KEY-1",
    "widgets": {
        "widgets": [],
        "size": 5
    }
}

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:

    {
        "startAt" : 0,
        "maxResults" : 10,
        "total": 200,
        "values": [
            { /* result 0 */ },
            { /* result 1 */ },
            { /* result 2 */ }
        ]
    }

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.

Ordering

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:

?orderBy=name
Order by "name" ascending

?orderBy=+name
Order by "name" ascending

?orderBy=-name
Order by "name" descending

Experimental methods

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.

Error responses

Most resources will return a response body in addition to the status code. Usually, the JSON schema of the entity returned is the following:

{
    "id": "https://docs.atlassian.com/jira/REST/schema/error-collection#",
    "title": "Error Collection",
    "type": "object",
    "properties": {
        "errorMessages": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "errors": {
            "type": "object",
            "patternProperties": {
                ".+": {
                    "type": "string"
                }
            },
            "additionalProperties": false
        },
        "status": {
            "type": "integer"
        }
    },
    "additionalProperties": false
}

Resources

/ppm/latest/project/

Copy project - POST: /ppm/latest/project/copy

Copy a Jira project.

POST /ppm/latest/project/copy

Parameter

Name	Type	Required	Description
sourceIssueKey	String	NO	issue key of the related project issue
templateProjectKey	String	YES	project key of the template project
targetProjectKey	String	YES	project key of the target project
targetProjectName	String	YES	project name of the target project
targetProjectLeadUsername	String	YES	project lead of the target project
targetProjectDescription	String	NO	project description of the target project
targetProjectUrl	String	NO	project url of the target project
targetProjectCategoryName	String	NO	project category of the target project
issueKeyMetadataKey	String	NO	metadata key for storing the issue key of the source issue
agileBoardCopyMetadata	String	NO	metadata key for the board name, which should be copied
filterCopyMetadata	String	NO	metadata key for the filter name, which is used in the board
newlyCreatedProjectKeyCfId	Long	NO	id of the custom field which stores the project link on the source issue after successful copy process
copyMetadata	Boolean	NO	Option if metadata of the source project should be copied (Default: false)
skipComment	Boolean	NO	Option if the comment creation on the source issue should be skipped (Default: false)
createIssueLinks	Boolean	NO	Option if issue links should be created (Default: true)
copyVersions	Boolean	NO	Option if versions from source project should be copied (Default: false)
copyComponents	Boolean	NO	Option if components from source project should be copied (Default: false)
copyIssues	Boolean	NO	Option if issues from source project should be copied (Default: false)
copyRequestType	Boolean	NO	Option if request types from source project should be copied (Default: false - JSD only)
copyPortal	Boolean	NO	Option if portal from source project should be copied (Default: false - JSD only)
copySLA	Boolean	NO	Option if SLA settings from source project should be copied (Default: false - JSD only)
copyQueue	Boolean	NO	Option if queues from source project should be copied (Default: false - JSD only)
copyCustomerPermission	Boolean	NO	Option if customer permissions from source project should be copied (Default: false - JSD only)

Example

{
  "sourceIssueKey":"ISSUE-123",
  "templateProjectKey":"TEMP",
  "targetProjectKey":"DEMO",
  "targetProjectName":"Demo Project",
  "targetProjectLeadUsername":"demouser",
  "targetProjectDescription":"This is a demo project.",
  "targetProjectUrl":"https://catworkx.com",
  "targetProjectCategoryName":"Demo",
  "issueKeyMetadataKey":"master_project",
  "agileBoardCopyMetadata":"connected_board",
  "filterCopyMetadata":"connected_filter",
  "newlyCreatedProjectKeyCfId":"123456",
  "copyMetadata":"false",
  "skipComment":"false",
  "createIssueLinks":"true",
  "copyVersions":"true",
  "copyComponents":"true",
  "copyIssues":"true",
  "copyRequestType":"false",
  "copyPortal":"false",
  "copySLA":"false",
  "copyQueue":"false",
  "copyCustomerPermission":"false"
}

Scheme

{
  "projectKey":"string",
  "label":"string",
  "url":"string"
}

Add link to project sidebar - POST: /ppm/latest/project/add-sidebar-link

Create a new link in the project sidebar.

POST /ppm/latest/project/add-sidebar-link

Parameter

Name	Type	Required	Description
projectKey	String	YES	project key where the link should be added to the sidebar
label	String	YES	label of the link item
url	String	YES	url destination of the link item

Example

{
  "projectKey":"ISSUE-123",
  "label":"TEMP",
  "url":"DEMO"
}

Scheme

{
  "projectKey":"string",
  "label":"string",
  "url":"string"
}

Getting started

Authentication

URI Structure

Expansion

Pagination

Ordering

Experimental methods

Special request and response headers

Error responses

Resources

/ppm/latest/project/

Parameter

Parameter