About

This is the reference for the Jira Cloud REST API. This API is the primary way to interact with Jira remotely, whether you are building an app, scripting interactions with Jira or developing any other integration. This page documents the REST resources available in Jira Cloud, along with expected HTTP response codes and sample requests.

Looking for the REST API reference for Jira Server? Follow the Jira Server REST API link.

A note about the V3 API

The v3 API is currently in beta. Note that while all endpoints from the v2 API are available, they are currently under development. This means that any endpoint can change at any time, although we will not introduce breaking changes without advanced notice.

Getting Started

If you haven't integrated with Jira Cloud before, start with Integrating with Jira Cloud guide. The guide will introduce you to the Atlassian Connect framework, as well as Jira features and services that you can use when building an app. Then, read our Getting started guide to learn how to set up a development environment and build a Jira Cloud app.

Authentication

Authentication for Atlassian Connect apps

Atlassian Connect apps use JSON Web Tokens (JWT) for authentication. This is already built into the supported Atlassian Connect libraries. At a high level, a security context is exchanged when the app is installed, then this context is used to create and validate JWT tokens that are embedded in API calls. To learn more, read Authentication for Connect apps.

Authentication for other integrations

If you are building an integration that does not use Atlassian Connect, use OAuth 2.0 authorization code grants (also known as three-legged OAuth) for authentication. Note, the base URL for requests made via OAuth 2.0 authorization code grants is https://api.atlassian.com. If you are copying the examples in this document, you'll need to change the URLs from https://your-domain.atlassian.net/{api} to https://api.atlassian.com/ex/jira/{cloudid}/{api}. To learn more, read OAuth 2.0 authorization code grants (3LO).

Alternatively, you can use basic authentication, however we don't recommend this method unless you are building tools for internal use only, like scripts and bots. To learn more, read Basic auth for REST APIs.

Permissions

Most operations in this API have a required permission, which the calling user must have in order to use the operation. A permission can be granted directly to a user; or to a group, project role, or issue role that the user is a member of. For a detailed explanation, see Permissions overview. The most common permissions and how they are granted are listed below:

  • Permission to administer the Cloud site (for example, manage users, billing, and more): Users in the site-admins group have this permission. For details, see Manage groups.
  • Permission to administer Jira: Granted by the Jira Administrators global permission. Users in the administrators group have this permission. For details, see Manage groups and Managing global permissions.
  • Permission to administer a project in Jira: Granted by the Administer projects project permission for a project. This can be granted in a variety of ways, for example, granted to a user, a group, a project role, and more. For details, see Managing project permissions.
  • Permission to access a project in Jira: Granted by the Browse projects project permission for a project. This can be granted in a variety of ways, for example, granted to a user, a group, a project role, and more. For details, see Managing project permissions.
  • Permission to log in to Jira: Granted by the Jira Users global permission. Users in the [product]-users (for example, jira-software-users) group have this permission. For details, see Manage groups and Managing global permissions.

Expansion

To simplify API responses, the Jira REST API uses resource expansion, which means that the API will only return parts of a resource when explicitly requested.

If you want to expand part of a resource in a request, use the expand query parameter to specify a comma-separated list of entities to be expanded, identifying each of them by name. For example, the following request will expand information about display name of each field as well as the HTML-rendered field values of the JRACLOUD-34423 issue:

https://jira.atlassian.com/rest/api/~ver~/issue/JRACLOUD-34423?expand=names,renderedFields

To discover what entities can be expanded in the request, refer to the expand property in the parent object. In the JSON example below, the resource declares widgets as expandable.

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

You can use the . dot notation to expand nested entities. For example ?expand=widgets.fringels would expand the widgets collection as well as the fringel property on each widget.

Pagination

The Jira Cloud REST API uses pagination to improve performance for all Jira Cloud users. Pagination is enforced for methods that could return a large collection of items. When you make a request to a paged API, the response will wrap the returned array of values in a JSON object with paging metadata, for example:

1
2
3
4
5
6
7
8
9
10
11
{
    "startAt" : 0,
    "maxResults" : 10,
    "total": 200,
    "isLast": false,
    "values": [
        { /* result 0 */ },
        { /* result 1 */ },
        { /* result 2 */ }
    ]
}

Where:

  • startAt is the index of the first item returned in the page of results.
  • maxResults is the maximum number of items that can be returned per page. Each API endpoint may have a different limit for the number of items returned, and these limits may change without notice.
  • total (optional) is the total number of items contained in all pages. This number may change as the client requests the subsequent pages, therefore the client should always assume that the requested page can be empty.
  • isLast (optional) indicates whether the page returned is the last one.

Ordering

Some Jira REST API resources support ordering of the elements in the response on a specific field. Refer to the endpoint's documentation to confirm whether ordering of the response is supported for this method, and which fields can be used in ordering. The list can be ordered in ascending or descending order, with ascending being the default one.

You can order the elements in response on a given field using the orderBy query parameter with - or + signs to specify ordering. In particular:

  • ?orderBy=name to order by name field ascending.
  • ?orderBy=+name to order by name field ascending.
  • ?orderBy=-name to order by name field descending.

Asynchronous Methods

This functionality is marked as experimental.

Some Jira REST API resources may trigger long-running or computationally expensive tasks. In this case, the method will schedule an asynchronous task and return a 303 (See Other) response, indicating the location of the queued task in the Location header. You can query this task systematically to get progress updates.

When the task eventually finishes, the bean will contain the result field. This result may have a different type, depending on the method. Refer to the endpoint's documentation for more information.

Note that asynchronous tasks are not guaranteed to be run in order. In other words, if you rely on the sequence of execution of your tasks, you need to start the next one only after all the prerequisite tasks have finished.

Experimental Methods

Methods marked as experimental may change without notice.

We are open to your feedback on the these methods. Report your suggestions and bugs for experimental APIs in the ACJIRA project or using the feedback button at the top of the page.

Special Headers

The following request and response headers define important metadata for the Jira Cloud REST API resources.

  • 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-atlassian-force-account-id (request): Operations with the x-atlassian-force-account-id: true header will behave as if GDPR changes are enforced (for example, deprecated fields removed). Use this header to test if your integration is GDPR-compliant. See the migration guide for details.
  • X-AUSERNAME (response): This response header contains either the username of the authenticated user or anonymous. Note that this header is not returned if the request includes the x-atlassian-force-account-id: true header.
  • X-AACCOUNTID (response): This response header contains the Atlassian account ID of the authenticated user.

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "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
}

Application-properties

Get application property

GET /rest/api/3/application-properties

Returns all application properties or a single application property.

If you specify a value for the key parameter, then a single application property is returned as an object (not in an array). Otherwise, an array of all editable application properties is returned. See Set application property for descriptions of editable properties.

Permissions required: Administer Jira global permission.

Apps cannot access this REST resource.

Request

Query parameters
key

string

The key of the application property.

permissionLevel

string

The permission level of all items being returned in the list.

keyFilter

string

When a key isn't provided, this filters the list of results by the application property key using a regular expression. For example, using jira.lf.* will return all application properties with keys that start with jira.lf..

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/api/3/application-properties' \
  --header 'Accept: application/json'

Responses

Returned if the request is successful.

Content typeValue
application/json

Array<ApplicationPropertyBean>

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[
  {
    "id": "jira.home",
    "key": "jira.home",
    "value": "/var/jira/jira-home",
    "name": "jira.home",
    "desc": "Jira home directory",
    "type": "string",
    "defaultValue": ""
  },
  {
    "id": "jira.clone.prefix",
    "key": "jira.clone.prefix",
    "value": "CLONE -",
    "name": "The prefix added to the Summary field of cloned issues",
    "type": "string",
    "defaultValue": "CLONE -"
  }
]

Get advanced settings

GET /rest/api/3/application-properties/advanced-settings

Returns the application properties that are accessible on the Advanced Settings page. To navigate to the Advanced Settings page in Jira, choose the Jira icon > Jira settings > System, General Configuration and then click Advanced Settings (in the upper right).

Permissions required: Administer Jira global permission.

Apps cannot access this REST resource.

Request

There are no parameters for this request.

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/api/3/application-properties/advanced-settings' \
  --header 'Accept: application/json'

Responses

Returned if the request is successful.

Content typeValue
application/json

Array<ApplicationPropertyBean>

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[
  {
    "id": "jira.home",
    "key": "jira.home",
    "value": "/var/jira/jira-home",
    "name": "jira.home",
    "desc": "Jira home directory",
    "type": "string",
    "defaultValue": ""
  },
  {
    "id": "jira.clone.prefix",
    "key": "jira.clone.prefix",
    "value": "CLONE -",
    "name": "The prefix added to the Summary field of cloned issues",
    "type": "string",
    "defaultValue": "CLONE -"
  }
]

Set application property

PUT /rest/api/3/application-properties/{id}

Changes the value of an application property. For example, you can change the value of the jira.clone.prefix from its default value of CLONE - to Clone - if you prefer sentence case capitalization. Editable properties are described below along with their default values.

Advanced settings

The advanced settings below are also accessible in Jira.

KeyDescriptionDefault value
jira.clone.prefixA string of text that automatically precedes the title of a cloned issue.CLONE -
jira.date.picker.java.formatThe date format for the Java (server-side) generated dates. This must be the same as the jira.date.picker.javascript.format format setting.d/MMM/yy
jira.date.picker.javascript.formatThis date format is for the JavaScript (client-side) generated dates. This must be the same as the jira.date.picker.java.format format setting.%e/%b/%y
jira.date.time.picker.java.formatThe date format for the Java (server-side) generated date times. This must be the same as the jira.date.time.picker.javascript.format format setting.dd/MMM/yy h:mm a
jira.date.time.picker.javascript.formatThis date format is for the JavaScript (client-side) generated date times. This must be the same as the jira.date.time.picker.java.format format setting.%e/%b/%y %I:%M %p
jira.issue.actions.orderThe default order of actions (such as Comments or Change history) displayed on the issue view.asc
jira.table.cols.subtasksThe columns to show while viewing sub-task issues in a table. For example, a list of sub-tasks on a particular issue.issuetype, status, assignee, progress
jira.view.issue.links.sort.orderThe sort order of the list of issue links on the issue view.type, status, priority
jira.comment.collapsing.minimum.hiddenThe minimum number of comments required for comment collapsing to occur. A value of 0 disables comment collapsing.4
jira.newsletter.tip.delay.daysThe number of days before a prompt to sign up to the Jira Insiders newsletter is shown. A value of -1 disables this functionality.7

Look and feel

The settings listed below adjust the look and feel.

KeyDescriptionDefault value
jira.lf.date.timeLook and feel of the time format.h:mm a
jira.lf.date.dayLook and feel of the day format.EEEE h:mm a
jira.lf.date.completeLook and feel of the date and time format.dd/MMM/yy h:mm a
jira.l