Welcome to the Jira Software Cloud REST API reference. You can use this REST API to build add-ons for Jira Software, develop integrations between Jira Software and other applications, or script interactions with Jira Software. This page documents the REST resources available in Jira Software Cloud, along with expected HTTP response codes and sample requests.

Jira Software is built on the Jira platform. As such, there is an overlap in functionality between what is provided by Jira Software and what is provided by the Jira platform. The REST API reference for the Jira Cloud platform is here: Jira Cloud platform REST API.

Authentication

Authentication for Atlassian Connect add-ons

If you are integrating with the Jira REST APIs via an Atlassian Connect add-on, API calls are authenticated via JWT (JSON Web Tokens). This is built into the supported Atlassian Connect libraries. At a high level, authentication works by the add-on exchanging a security context with the application. This context is used to create and validate JWT tokens, embedded in API calls. To learn more, read the Atlassian Connect authentication documentation.

Some integration APIs such as Feature Flags are only available to Atlassian Connect apps that define the relevant module related to that API. Other APIs, such as the Development Information, Builds, and Deployments APIs are available to both Atlassian Connect apps and on-premises tools using Jira Software's OAuth credentials for system-to-system integration.

Authentication for REST API requests

If you are integrating directly with the REST APIs, rather than via an Atlassian Connect add-on, use one of the authentication methods listed below:

• OAuth 2.0 - This token-based method is the recommended method. It is more flexible and secure than other options.
• OAuth 1.0a - This is a legacy authentication method and, therefore, isn't recommended. Instead use OAuth 2.0.
• Basic HTTP - This method is only recommended for tools like scripts or bots. It is easier to implement, but much less secure.

Note, 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.

Authentication for on-premises integrations

If you are integrating an on-premises app with the Jira REST APIs, API calls are authenticated via an OAuth token. To obtain a token, create a set of OAuth credentials with permissions for the APIs that app needs to access. Use the credentials to request a token by calling https://api.atlassian.com/oauth/token. See Integrating Jira Software Cloud with on-premises tools for details. Note that only the Development Information, Builds, and Deployments APIs are currently available for on-premises integrations. To simplify development, we have a separate downloadable API spec.

Atlassian has developed an open source plugin for Jenkins, which you can use to bootstrap development. This plugin uses the authentication method described above and calls the Builds and Deployments APIs.

Base URL differences

When building an on-premises integration, the base URL for API operations is different to the base URL used for Connect apps. This is because requests from on-premises integrations (OAuth) need to be sent via the Atlassian API proxy at https://api.atlassian.com.

This document does not display the base URLs used by on-premises integrations. Therefore, when using an operation, you must replace https://your-domain.atlassian.net/rest/{type}/{version}/{operation} with https://api.atlassian.com/jira/{type}/{version}/cloud/{cloudId}/{operation}.

For example:

• Builds API: Change the path from https://your-domain.atlassian.net/rest/builds/0.1/bulk to https://api.atlassian.com/jira/builds/0.1/cloud/{cloudId}/bulk.
• Development Information: Change the path from https://your-domain.atlassian.net/rest/devinfo/0.10/bulk to https://api.atlassian.com/jira/devinfo/0.1/cloud/{cloudId}/bulk. Note the version change.
• Deployments: Change the path from https://your-domain.atlassian.net/rest/deployments/0.1/bulk to https://api.atlassian.com/jira/deployments/0.1/cloud/{cloudId}/bulk.

Note, get the cloudId for a Jira instance by calling https://your-domain.atlassian.net/_edge/tenant_info.

URI structure

Jira Agile'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 Agile 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 Agile's REST API resource have the following structure:

1
2
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 1. However, there is also a symbolic version, called latest, which resolves to the latest version supported by the given Jira Software Cloud instance. For example, if you wanted to retrieve the JSON representation of a board with boardId=123, from a Jira Software Cloud instance at https://jira.atlassian.net, you would access:

1
2
https://jira.atlassian.net/rest/agile/latest/board/123

Pagination

Pagination is used for the Jira REST APIs to conserve server resources and limit response size for resources that return potentially large collection of items. A request to a pages API will result in a values array wrapped in a JSON object with some paging metadata, like this:

Request

1
2
http://host:port/context/rest/api-name/api-version/resource-name?startAt=0&maxResults=10

Response

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

• startAt - the item used as the first item in the page of results.
• maxResults - how many results to return per page.
• total - the number of items that the calling user has permissions for. This number may change while the client requests the next pages. A client should always assume that the requested page can be empty. REST API consumers should also consider the field to be optional. This value may not be included in the response, if it is too expensive to calculate.

Clients can use the startAt, maxResults, and total parameters to retrieve the desired number of results. Note, each API resource or method may have a different limit on the number of items returned, which means you can ask for more than you are given. The actual number of items returned is an implementation detail and this can be changed over time.

Experimental methods

Methods marked as experimental may change without an earlier notice. We are looking for your feedback for these methods.

Query parameters

All query parameters for the resources described below are optional, unless specified otherwise.

Special Request and Response headers

• X-Atlassian-Token (request): Operations that accept multipart/form-data must include the X-Atlassian-Token: no-check header in requests. Otherwise the request will be blocked by XSRF protection.
• X-AACCOUNTID (response): This response header contains the Atlassian account ID of the authenticated user.

Jira Software field input formats

Jira Software provides a number of custom fields, which are made available in the Jira platform REST API. The custom fields are: Sprint, Epic link, Epic name, and Story points.

You can read and edit these custom fields via the issue resource of the Jira Platform REST API. In order to identify the custom field that you want to read or edit, you'll need the custom field id. To obtain the custom field id, retrieve the list of fields from the fields resource and search for the custom field. It's better to find the field based on the schema where possible (e.g. the Sprint field is identified by "com.pyxis.greenhopper.jira:gh-sprint"), as custom field names are mutable. The custom field id will be in the id, (e.g. id: customfield_10007).

If you only need to get the value of the custom field for a single issue, you may want to use the issue resource provided by the Jira Software REST API instead. This resource returns the issue with all Jira Software-specific fields, including the fields listed above. These fields will also be formatted as proper fields with keys, in the response.

Note, Jira Software also has a number of internal custom fields, which are: Epic Color, Epic Status, Flag, Rank. These internal fields shouldn't be read or updated using the REST API and are not documented below.

Sprint custom field

The Sprint custom field contains a list of sprints for a given issue. This list includes the active/future sprint that the issue is currently in, as well as any closed sprints that the issue was in previously.

For legacy reasons, the Get issue (Jira platform) method returns the Sprint custom field with sprints in a toString format, which is difficult to parse. See the example below.

Deprecation notice: The toString representation of sprints in the Sprint custom field that is returned by Get issue (Jira platform) will soon be removed. See the notice.

Example - Get issue (Jira platform) response

1
2
customfield_11458": [
    "com.atlassian.greenhopper.service.sprint.Sprint@1bf75fd[id=1,rapidViewId=1,state=CLOSED,name=Sprint 1,goal=Sprint 1 goal,startDate=2016-06-06T21:30:53.537+10:00,endDate=2016-06-20T21:30:00.000+10:00,completeDate=2016-06-06T21:30:57.523+10:00,sequence=1]",
    "com.atlassian.greenhopper.service.sprint.Sprint@1689feb[id=2,rapidViewId=1,state=FUTURE,name=Sprint 2,goal=Sprint 2 goal,startDate=<null>,endDate=<null>,completeDate=<null>,sequence=2]"
]

If you want to parse the sprint information, use either the Get issue (Jira Software) method or Get issue (Jira platform) method with expanded versionedRepresentations instead, both of which return sprints in a proper format. See the example below.

Example - Get issue (Jira platform) response with expanded versionedRepresentations

1
2
"customfield_10021": {
    "1": [
        "com.atlassian.greenhopper.service.sprint.Sprint@1bf75fd[id=1,rapidViewId=1,state=CLOSED,name=Sprint 1,goal=Sprint 1 goal,startDate=2016-06-06T21:30:53.537+10:00,endDate=2016-06-20T21:30:00.000+10:00,completeDate=2016-06-06T21:30:57.523+10:00,sequence=1]",
        "com.atlassian.greenhopper.service.sprint.Sprint@1689feb[id=2,rapidViewId=1,state=FUTURE,name=Sprint 2,goal=Sprint 2 goal,startDate=<null>,endDate=<null>,completeDate=<null>,sequence=2]"
    ],
    "2": [
        {
            "id": 1,
            "name": "Sprint 1",
            "state": "closed",
            "boardId": 1
        },
        {
            "id": 2,
            "name": "Sprint 2",
            "state": "future",
            "boardId": 1
        }
    ]
}

If you want to update a sprint, you need to know the sprint id, which is a number. See the example below. Note, an issue can only be in one active or future sprint at a time, and only the active/future sprint can edited.

Example - Update issue request

1
2
"customfield_10021": 2

Epic link custom field

The Epic link custom field contains the key of an epic that a given issue belongs to. Be aware that only the issue key of the existing epic can be set. Also, the Epic link cannot be set for sub-tasks and epics.

Example

1
2
"customfield_11458": "EPIC-1"

Epic Name

The Epic name custom field contains the name of an epic that a given issue belongs to. Be aware that only the issue key of the existing epic can be set. Also, the epic link cannot be set for sub-tasks and epics.

Example

1
2
"customfield_11410": "Epic Name"

Estimation

Jira Software provides a Story Points custom field, however the field is just a regular numeric field. The type of estimation and field used for estimation is determined by the board configuration. You can get this from the board configuration resource. Note that if the estimation field is not on a screen, it cannot be edited, and you should use the Estimate issue for board method instead.