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.

Copy
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:

Copy
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-AUSERNAME (response) - This response header contains either the username of the logged-in user or anonymous.
  • X-Atlassian-Token (request) - Methods that accept multipart/form-data will only process requests with X-Atlassian-Token: no-check header. Otherwise the request will be blocked by XSRF protection.

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:

Copy
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

Copy
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)

Copy
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>/a>.

Apps cannot access this REST resource.

Request

There are no parameters for this request.

Example

Copy
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)

Copy
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.lf.date.dmyLook and feel of the date format.dd/MMM/yy
jira.date.time.picker.use.iso8061When enabled, sets Monday as the first day of the week in the date picker, as specified by the ISO8601 standard.false
jira.lf.logo.urlThe URL of the logo image file./images/icon-jira-logo.png
jira.lf.logo.show.application.titleControls the visibility of the application title on the sidebar.false
jira.lf.favicon.urlThe URL of the favicon./favicon.ico
jira.lf.favicon.hires.urlThe URL of the high resolution favicon./images/64jira.png
jira.lf.top.adg3.bgcolourThe background color of the sidebar.#0747A6
jira.lf.top.adg3.textcolourThe color of the text and logo of the sidebar.#DEEBFF
jira.lf.hero.button.base.bg.colour#3b7fc4
jira.titleThe text for the application title. The application title can also be set in General settings.Jira
jira.option.globalsharingbooleantrue
xflow.product.suggestions.enabledIndicate whether or not to expose product suggestions for other Atlassian products within Jira.true

Other settings

KeyDescriptionDefault value
jira.issuenav.criteria.autoupdateSupports instant updates to search criteria.true

Note: Be careful when changing application properties and advanced settings.

Permissions required: Administer Jira global permission>/a>.

Apps cannot access this REST resource.

Request

Path parameters
id Required

string

The key of the application property to update.

Body parameters
id

string

The ID of the application property, for example jira.newsletter.tip.delay.days.

value

string

The new value, for example -1.

Example

Copy
1
2
3
4
5
6
7
8
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/api/3/application-properties/{id}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "jira.home",
  "value": "/var/jira/jira-home"
}'

Responses

Returned if the request is successful.

Content typeValue
application/json

ApplicationPropertyBean

Applicationrole

Get all application roles

GET /rest/api/3/applicationrole

Returns all ApplicationRoles in the system. Will also return an ETag header containing a version hash of the collection of ApplicationRoles.

Apps cannot access this REST resource.

Request

There are no parameters for this request.

Example

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

Responses

Returns all ApplicationRoles in the system

Content typeValue
application/json

Array<ApplicationRoleBean>

Example response (application/json)

Copy
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
27
28
29
30
31
32
33
34
35
36
37
38
39
[
  {
    "key": "jira-software",
    "groups": [
      "jira-software-users",
      "jira-testers"
    ],
    "name": "Jira Software",
    "defaultGroups": [
      "jira-software-users"
    ],
    "selectedByDefault": false,
    "defined": false,
    "numberOfSeats": 10,
    "remainingSeats": 5,
    "userCount": 5,
    "userCountDescription": "5 developers",
    "hasUnlimitedSeats": false,
    "platform": false
  },
  {
    "key": "jira-core",
    "groups": [
      "jira-core-users"
    ],
    "name": "Jira Core",
    "defaultGroups": [
      "jira-core-users"
    ],
    "selectedByDefault": false,
    "defined": false,
    "numberOfSeats": 1,
    "remainingSeats": 1,
    "userCount": 0,
    "userCountDescription": "0 users",
    "hasUnlimitedSeats": false,
    "platform": true
  }
]

Get application role

GET /rest/api/3/applicationrole/{key}

Returns the ApplicationRole with passed key if it exists.

Apps cannot access this REST resource.

Request

Path parameters
key Required

string

the key of the role to use.

Example

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

Responses

Returns the ApplicationRole if it exists.

Content typeValue
application/json

ApplicationRoleBean

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "key": "jira-software",
  "groups": [
    "jira-software-users",
    "jira-testers"
  ],
  "name": "Jira Software",
  "defaultGroups": [
    "jira-software-users"
  ],
  "selectedByDefault": false,
  "defined": false,
  "numberOfSeats": 10,
  "remainingSeats": 5,
  "userCount": 5,
  "userCountDescription": "5 developers",
  "hasUnlimitedSeats": false,
  "platform": false
}

Attachment

Get global attachment settings

GET /rest/api/3/attachment/meta

Returns the global attachment settings, that is, whether attachments are enabled and the maximum attachment size allowed.

Note that there are also project permissions that restrict whether users can create and delete attachments or not.

Permissions required: None.

App scope requiredREAD

OAuth scopes required
read:jira-work

Request

There are no parameters for this request.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/api/3/attachment/meta' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returned if the request is successful.

Content typeValue
application/json

AttachmentMetaBean

Example response (application/json)

Copy
1
2
3
4
{
  "enabled": true,
  "uploadLimit": 1000000
}

Get attachment metadata

GET /rest/api/3/attachment/{id}

Returns the metadata for an attachment. Note that the attachment itself is not returned.

Permissions required: None, however the calling user must have permission to view the issue that the attachment belongs to.

App scope requiredREAD

OAuth scopes required
read:jira-work

Request

Path parameters
id Required

string

The ID of the attachment.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/api/3/attachment/{id}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returned if the request is successful.

Content typeValue
application/json

AttachmentBean

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "id": 10000,
  "self": "https://your-domain.atlassian.net/rest/api/3/attachments/10000",
  "filename": "picture.jpg",
  "author": {
    "self": "http://your-domain.atlassian.net/rest/api/3/user?username=mia",
    "key": "mia",
    "accountId": "99:27935d01-92a7-4687-8272-a9b8d3b2ae2e",
    "name": "mia",
    "avatarUrls": {
      "48x48": "http://your-domain.atlassian.net/secure/useravatar?size=large&ownerId=mia",
      "24x24": "http://your-domain.atlassian.net/secure/useravatar?size=small&ownerId=mia",
      "16x16": "http://your-domain.atlassian.net/secure/useravatar?size=xsmall&ownerId=mia",
      "32x32": "http://your-domain.atlassian.net/secure/useravatar?size=medium&ownerId=mia"
    },
    "displayName": "Mia Krystof",
    "active": false
  },
  "created": "2018-09-25T04:33:38.641+0000",
  "size": 23123,
  "mimeType": "image/jpeg",
  "content": "https://your-domain.atlassian.net/jira/attachments/10000",
  "thumbnail": "https://your-domain.atlassian.net/jira/secure/thumbnail/10000"
}

Delete attachment

DELETE /rest/api/3/attachment/{id}

Deletes an attachment from an issue.

Permissions required: Any of the following permissions in the project that the issue is in:

  • Delete own attachments project permission to delete an attachment created by the calling user.
  • Delete all attachments project permission to delete an attachment created by any user.

App scope requiredDELETE

OAuth scopes required
write:jira-work

Request

Path parameters
id Required

string

The ID of the attachment.

Example

Copy
1
2
3
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/api/3/attachment/{id}' \
  --header 'Authorization: Bearer <access_token>'

Responses

Returned if the request is successful.

Get all metadata for an expanded attachment

Experimental

GET /rest/api/3/attachment/{id}/expand/human

Returns the metadata for the contents of an attachment, if it is an archive, and metadata for the attachment itself. For example, if the attachment is a ZIP archive, then information about the files in the archive is returned and metadata for the ZIP archive. Currently, only the ZIP archive format is supported.

Use this method to retrieve data that is presented in the UI, as this method returns the metadata for the attachment itself, such as the attachment's ID and name. Otherwise, use Get contents metadata for an expanded attachment, which only returns the metadata for the attachment's contents.

Permissions required: None, however the calling user must have permission to view the issue that the attachment belongs to.

App scope requiredREAD

OAuth scopes required
read:jira-work

Request

Path parameters
id Required

string

The ID of the attachment.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/api/3/attachment/{id}/expand/human' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returned if the request is successful. If an empty list is returned in the response, the attachment is empty, corrupt, or not an archive.

Content typeValue
application/json

HumanReadableArchive

Example response (application/json)

Copy
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
27
28
29
{
  "id": 7237823,
  "name": "images.zip",
  "entries": [
    {
      "path": "MG00N067.JPG",
      "index": 0,
      "size": "119 kB",
      "mediaType": "image/jpeg",
      "label": "MG00N067.JPG"
    },
    {
      "path": "Allegro from Duet in C Major.mp3",
      "index": 1,
      "size": "1.36 MB",
      "mediaType": "audio/mpeg",
      "label": "Allegro from Duet in C Major.mp3"
    },
    {
      "path": "long/path/thanks/to/lots/of/subdirectories/inside/making/it/quite/hard/to/reach/the/leaf.txt",
      "index": 2,
      "size": "0.0 k",
      "mediaType": "text/plain",
      "label": "long/path/thanks/to/.../reach/the/leaf.txt"
    }
  ],
  "totalEntryCount": 39,
  "mediaType": "application/zip"
}

Get contents metadata for an expanded attachment

Experimental

GET /rest/api/3/attachment/{id}/expand/raw

Returns the metadata for the contents of an attachment, if it is an archive. For example, if the attachment is a ZIP archive, then information about the files in the archive is returned. Currently, only the ZIP archive format is supported.

Use this method if you are processing the data without presenting it in the UI, as this method only returns the metadata for the contents of the attachment. Otherwise, to retrieve data to present in the UI, use Get all metadata for an expanded attachment which also returns the metadata for the attachment itself, such as the attachment's ID and name.

Permissions required: None, however the calling user must have permission to view the issue that the attachment belongs to.

App scope requiredREAD

OAuth scopes required
read:jira-work

Request

Path parameters
id Required

string

The ID of the attachment.

Example

Copy
1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/api/3/attachment/{id}/expand/raw' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returned if the request is successful. If an empty list is returned in the response, the attachment is empty, corrupt, or not an archive.

Content typeValue
application/json

AttachmentArchiveImpl

Example response (application/json)

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "entries": [
    {
      "entryIndex": 0,
      "name": "Allegro from Duet in C Major.mp3",
      "size": 1430174,
      "mediaType": "audio/mpeg"
    },
    {
      "entryIndex": 1,
      "name": "lrm.rtf",
      "size": 331,
      "mediaType": "text/rtf"
    }
  ],
  "totalEntryCount": 24
}

Auditing

Get audit records

GET /rest/api/3/auditing/record

Returns a list of audit records. The list can be filtered to include items:

  • containing a string in at least one field. For example, providing up will return all audit records where one or more fields contains words such as update.
  • created on or after a date and time.
  • created or or before a date and time.
  • created during a time period.

Permissions required: Administer Jira global permission.

App scope requiredREAD

Request

Query parameters
offset

integer

The number of records to skip before returning the first result.

Default: 0, Format: int32
limit

integer

The maximum number of results to return. The maximum is 1000.

Default: 1000, Format: int32
filter

string

The query string.

from

string

The date and time on or after which returned audit records must have been created. If to is provided from must be before to or the result set will be empty.

Format: date-time
to

string

The date and time on or before which returned audit results must have been created. If from is provided to must be after from or the result set will be empty.

Format: date-time

Example

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

Responses