The REST APIs are for developers who want to integrate Jira Service Management with other applications or administrators who want to automate their workflows and processes.

Jira Service Management is built upon the Jira platform. As such, in Jira Service Management you have access to the Jira platform REST APIs.

• Browse the Jira platform REST APIs

Permissions control the level of a user's access to the Jira Service Management instance, while roles are how the permissions are assigned to individual users.

For detailed information on roles and permissions, see Permissions overview and Setting up service management users.

The Jira Service Management REST API uses the same authentication methods as Jira Cloud platform.

Forge apps

Forge apps use REST API scopes when authenticating with Jira Service Management Cloud. For details see Add scopes to call an Atlassian REST API.

The URIs for Forge app REST API calls have this structure:

https://<site-url>/rest/servicedeskapi/<resource-name>

For example, https://<site-url>/rest/servicedeskapi/request/DEMO-1

Connect apps

For Connect apps, authentication (JWT-based) is built into the Connect libraries. Authorization is implemented using either scopes (shown as App scope required for operations on this page) or user impersonation. For details, see Security for Connect apps.

The URIs for Connect app REST API calls have this structure:

https://<site-url>/rest/servicedeskapi/<resource-name>

For example, https://<site-url>/rest/servicedeskapi/request/DEMO-1

Other integrations

For integrations that are not Forge or Connect apps, use OAuth 2.0 authorization code grants (3LO) for security (3LO scopes are shown as for operations OAuth scopes required). For details, see OAuth 2.0 (3LO) apps.

The URIs for OAuth 2.0 (3LO) app REST API calls have this structure:

https://api.atlassian.com/ex/jira/<cloudId>/rest/servicedeskapi/<resource-name>

For example, https://api.atlassian.com/ex/jira/35273b54-3f06-40d2-880f-dd28cf8daafa/rest/servicedeskapi/request/DEMO-1

Ad-hoc API calls

For personal scripts, bots, and ad-hoc execution of the REST APIs use basic authentication. For details, see Basic auth for REST APIs.

The URIs for basic authentication REST API calls have this structure:

https://<site-url>/rest/servicedeskapi/<resource-name>

For example, https://your-domain.atlassian.net/rest/servicedeskapi/request/DEMO-1

Your app can request access to the Jira Service Management REST APIs by using the correct scopes.

• Scopes for Forge and 3LO apps
• Scopes for Connect apps.

It is also worth noting that the ability of Customers to raise Requests depends on the service desk type, which can be:

• Public (sign up): Anyone who has the service desk URL can submit requests, and a user (customer) is created for them when a request is submitted.
• Open: Any user in the system can submit requests, they don’t need to be associated with the service desk.
• Closed: Only users associated with the service desk can submit requests.

For more details, see How to manage access to your Jira Service Management Cloud in the Jira Service Management Cloud documentation.

• Status 200 Returned if the requested content (GET) is returned or content is updated (PUT).
• Status 201 Returned if new records are created (PUT).
• Status 204 Returned where the request may or may not have been actioned, but the outcome is as expected. For example, the request was to remove a customer from an organization, but the customer was not associated with the organization.
• Status 400 Returned if the request was invalid.
• Status 401 Returned if the user is not logged in. Resolve by logging the user in and reissuing the call.
• Status 403 Returned if the user does not have the necessary permission to access the resource or run the method.
• Status 404 Returned if the passed path parameters do not correspond to an object in the instance, for example, no Organization exists for a passed ID.
• Status 412 Returned if the API is experimental but the X-ExperimentalApi: opt-in header was not passed. For more details, see Experimental methods.

Resources will return a response body in addition to the error status codes. The returned entity for errors is as follows:

1
2
{
  "errorMessage": "Here is an error message",
  "i18nErrorMessage": {
    "i18nKey": "some.error.key",
    "parameters": []
  }
}

Methods marked as experimental may change without notice. To use experimental methods, you must include the X-ExperimentalApi: opt-in header in your requests. Use of this header indicates that you are opting into the experimental preview. Once a resource or method moves out of the experimental phase, then the header will no longer be required or checked.

Feedback on the experimental APIs is welcome and can be provided by submitting a feature request or suggestion through the Atlassian Ecosystem Help Center or the Jira Service Management Ecosystem.

The Jira Service Management REST API uses resource expansion, which means that some parts of a resource are not returned unless specified in the request. This simplifies responses and minimizes network traffic.

Use the expand query parameter to specify the list of entities that you want to be expanded, identifying each of them by name. For example, appending ?expand=serviceDesk&expand=requestType to a request’s URI results in the inclusion of the service desk and request type details in the response. The following URL would be used to get that information for the request with the ID JSD-1:

1
2
http://host:port/context/rest/servicedeskapi/request/JSD-1?expand=serviceDesk&expand=requestType

Alternatively, you can pass the list of entities you want to be expanded as a single comma-separated parameter, as in:

1
2
http://host:port/context/rest/servicedeskapi/request/JSD-1?expand=serviceDesk,requestType

To discover the expansion identifiers for each entity, look at the _expands property in the parent object. In the JSON example below, the resource declares participant, status, sla, requestType, and serviceDesk as expandable.

1
2
{
    "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk"
    ],
    "issueId": "107001",
    "issueKey": "HELPDESK-1",
    "requestTypeId": "11001",
    "serviceDeskId": "10001",
    ...

The Jira Service Management REST API uses pagination to improve performance. Pagination is enforced for operations that could return a large collection of items. When you make a request to a paginated resource, the response wraps the returned array of values in a JSON object with paging metadata as follows: Request

1
2
http://host:port/context/rest/api-name/resource-name?start=0&limit=10

Response

1
2
{
    "start" : 0,
    "limit" : 10,
    "size" : 7,
    "isLastPage" : true,
    "values": [
        { /* result 0 */ },
        { /* result 1 */ },
        { /* result 2 */ }
        { /* result 3 */ }
        { /* result 4 */ }
        { /* result 5 */ }
        { /* result 6 */ }
    ]
}

Where:

• start is the index of the first item returned in the page of results.
• limit is the total number of items that could be returned per page, subject to the maximum server enforced limit for the resource’s method. If limit isn’t specified the default value of the resource is used.
• size is the number of items returned on this page.
• isLastPage indicates whether the page is the last page of results.

Clients can use the start, limit, and size parameters to retrieve the desired number of results. Each resource or method has a unique limit on the maximum number of items returned, which cannot be exceeded. If you request size which is larger than the limit, the number of items returned will be capped at the limit for that resource’s method. This behavior can be identified when the first page shows size is less than limit and isLastPage is false.

The limits set for each resource’s method is an implementation detail and may be changed.

By default, responses are translated based on the requesting user's language preference, or the Jira site default language if anonymous.

Use the requestLanguage query parameter to have responses translated in a specific language, providing an IETF BCP 47 language tag in the form (language code)-(country code) as the value. E.g. ?requestLanguage=en-US for English (United States). Both static text (e.g. error messages) and dynamic user-entered text (e.g. workflow status names) will be translated, if available.

The languages available are based on the installed languages in Jira. If the language tag specified does not match one of Jira's languages, then the query parameter will have no effect.

Dynamic user-entered translations can be edited in Jira administration for global objects (e.g. priority names) and in Language support under project administration for Service Desk projects (e.g. request type names).

The following request and response headers define important metadata for the Jira Service Management 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-ExperimentalApi (request): Experimental operations must include the X-ExperimentalApi: opt-in header in requests. Otherwise the request will not be processed. See Experimental methods for more details.
• X-AACCOUNTID (response): This response header contains the Atlassian account ID of the authenticated user.

For convenience, any of the resources that require a {serviceDeskId} path parameter also accept other identifiers.

For example, if a ServiceDesk(id: 15) corresponds to a Project(id: 10012, key: ABC), then issuing a request to any of:

1
2
/rest/servicedeskapi/servicedesk/ABC

/rest/servicedeskapi/servicedesk/projectKey:ABC

/rest/servicedeskapi/servicedesk/projectId:10012

/rest/servicedeskapi/servicedesk/serviceDeskId:15

is equivalent to issuing a request to:

1
2
/rest/servicedeskapi/servicedesk/15

Summary - A single line of text.

1
2

"summary": "An explanation is one line of text."

Description - Multiple lines of text.

1
2

"description": "A description is multiples lines of text\n separated by\n line feeds.",

Components - Multiple values addressed by 'name'.

1
2

"components" : [ { "name": "Active Directory"} , { "name": "Network Switch" } ]

Due date - A date in 'YYYY-MM-DD' format.

1
2

"duedate" : "2015-11-18"

Labels - An array of string values.

1
2

"labels" : ["examplelabelnumber1", "examplelabelnumber2"]

Checkbox custom field - A custom UI field that enables multiple values to be selected from a defined list of values, with values addressed by 'value' or id.

1
2

"customfield_11440" : [{ "value" : "option1"}, {"value" : "option2"}]

or

"customfield_11440" : [{ "id" : 10112}, {"id" : 10115}]

Date picker custom field - A custom UI field that enables a date in 'YYYY-MM-DD' format to be picked.

1
2

"customfield_11441" : "2015-11-18"

Date time picker custom field - A custom UI field enables a datetime in ISO 8601 ('YYYY-MM-DDThh:mm:ss.sTZD') format to be picked.

1
2

"customfield_11442" : "2015-11-18T14:39:00.000+1100"

Labels custom field - A custom UI field that is an array of strings.

1
2

"customfield_11443" : [ "rest_label1", "rest_label2" ]

Number custom field - A custom UI field that enables a number to be entered.

1
2

"customfield_11444" : 666

Radio button custom field - A custom UI field that enables a single value to be selected from a defined list of values, with values addressed by value or id.

1
2

"customfield_11445" : { "value": "option2" }

or

"customfield_11445" : { "id": 10112 }

Cascading select custom field - A custom UI field that enables a single parent value and then a related child value to be selected, with values addressed by value or id.

1
2

"customfield_11447" : { "value": "parent_option1", "child": { "value" : "p1_child1"} }

or

"customfield_11447" : { "id": 10112, "child": { "id" : 10115 } }

Multi-select custom field - A custom UI field that enables multiple values to be selected from a defined list of values, with values addressed by value or id.

1
2

"customfield_11448" : [ { "value": "option1" }, { "value": "option2" } ]

or

"customfield_11448" : [ { "id": 10112 }, { "id": 10115 } ]

Single-select custom field - A custom UI field that enables a single value to be selected from a defined list of values, with values address by value or id.

1
2

"customfield_11449" : { "value": "option3" }

or

"customfield_11449" : { "id": 10112 }

Multi-line text custom field - A custom UI field that enables multiple lines of text to be entered.

1
2

"customfield_11450": "Multiples lines of text\n separated by\n line feeds"

Text custom field - A custom UI field that enables a single line of text to be entered.

1
2

"customfield_11450": "A single line of text."

URL custom field - A custom UI field that enables a URL to be entered.

1
2

"customfield_11452" : "http://www.atlassian.com",

Single-user picker custom field - A custom UI field that enables a single user to be selected.

1
2

"customfield_11453" : { "name":"tommytomtomahawk" },

Multi-user picker custom field - A custom UI field that enables multiple users to be selected.

1
2

"customfield_11458" : [ { "name":"inigomontoya" }, { "name":"tommytomtomahawk" }]

Attachment - Attachments, using IDs of temporary attachments as provided by the /attachTemporaryFile API.

1
2
"attachment" : ["4786e3a5-52be-4d5b-bf3d-5f53e54f4559", "1187b2b7-8a75-4eac-88b2-b6e43129ef5c"]

The Jira Service Management REST API enable you to work with a range of objects from Jira Service Management. The main resources provided are: