REST API Reference

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.

Pagination

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

NameTypeRequiredDescription
sourceIssueKeyString

NO

issue key of the related project issue
templateProjectKeyString

YES

project key of the template project
targetProjectKeyString

YES

project key of the target project
targetProjectNameString

YES

project name of the target project
targetProjectLeadUsernameString

YES

project lead of the target project
targetProjectDescriptionString

NO

project description of the target project
targetProjectUrlString

NO

project url of the target project
targetProjectCategoryNameString

NO

project category of the target project 
issueKeyMetadataKeyString

NO

metadata key for storing the issue key of the source issue
agileBoardCopyMetadataString

NO

metadata key for the board name, which should be copied
filterCopyMetadataString

NO

metadata key for the filter name, which is used in the board
newlyCreatedProjectKeyCfIdLong

NO

id of the custom field which stores the project link on the source issue after successful copy process
copyMetadataBoolean

NO

Option if metadata of the source project should be copied (Default: false)
skipCommentBoolean

NO

Option if the comment creation on the source issue should be skipped (Default: false)
createIssueLinksBoolean

NO

Option if issue links should be created (Default: true)
copyVersionsBoolean

NO

Option if versions from source project should be copied (Default: false)
copyComponentsBoolean

NO

Option if components from source project should be copied (Default: false)
copyIssuesBoolean

NO

Option if issues from source project should be copied (Default: false)
copyRequestTypeBoolean

NO

Option if request types from source project should be copied (Default: false - (warning) JSD only)
copyPortalBoolean

NO

Option if portal from source project should be copied (Default: false - (warning) JSD only)
copySLABoolean

NO

Option if SLA settings from source project should be copied (Default: false - (warning) JSD only)
copyQueueBoolean

NO

Option if queues from source project should be copied (Default: false - (warning) JSD only)
copyCustomerPermissionBoolean

NO

Option if customer permissions from source project should be copied (Default: false - (warning) 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

NameTypeRequiredDescription
projectKeyString

YES

project key where the link should be added to the sidebar
labelString

YES

label of the link item
urlString

YES

url destination of the link item



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



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