Rate this page:
This is the reference for the Jira Service Management Cloud REST APIs. The REST APIs are for developers who want to integrate Jira Service Management with other applications or administrators that 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.
If you are writing an Atlassian Connect app, your app can request access to the Jira platform REST APIs by using the correct Jira platform Connect Scopes.
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 desk users.
Permission types
Roles
It is also worth noting that the ability of Customers to raise Requests depends on the service desk type, which can be:
For more details, see How to manage access to your Jira Service Management Cloud in the Jira Service Management Cloud documentation.
The Jira Service Management REST API uses the same authentication methods as Jira Cloud.
If you are building an Atlassian Connect app to interact with the Jira Service Management Cloud REST API, authentication is handled by JWT (JSON Web Token) technology. This is built into the supported Atlassian Connect libraries. At a high level, a security context is exchanged when the app is installed, and this context is used to create and validate JWT tokens, embedded in API calls. To learn more, read the Authentication for apps guide.
If you are integrating directly with the Jira Service Management Cloud REST APIs it is recommended to use OAuth authentication method. For implementations with low security requirements, such as scripts and bots, it is also possible to use Basic authentication method.
Jira Service Management uses cookie-based authentication in the browser. Therefore, you can call the REST API from JavaScript on a page and rely on the authentication that the browser has established.
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).
Scopes provide static authorization for Atlassian Connect apps. If you are using your own credentials to make REST calls, then these scopes do not apply.
Scopes are defined in the Connect app descriptor and specify the maximum set of actions that an app may perform: read, write, etc. This security level is enforced by Atlassian Connect and cannot be bypassed by app implementations.
For the list of Jira Service Management REST scopes, see Scopes.
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 pagination to conserve server resources and limit the size of responses. Pagination is enforced for methods that could return a large collection. When you make a request to a paged API, the response will wrap the returned values in a JSON object with paging metadata, as follows:
Request
1 2http://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.
To simplify API responses, the Jira Service Management REST API uses resource expansion: the API will only return parts of the resource when explicitly requested.
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 2http://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 2http://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", ...
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 Service Management REST API resources.
X-Atlassian-Token: no-check
header in requests.
Otherwise the request will be blocked by XSRF protection.X-ExperimentalApi: opt-in
header in requests.
Otherwise the request will not be processed. See Experimental methods for more details.For convenience, any of the resources that require a {serviceDeskId}
path parameter also accepts 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:
Resource | Description |
---|---|
customer | This resource represents customers within your Jira instance. Use it to create new customers. |
info | This resource provides details of the Jira Service Management software version, builds, and related links. |
organization | This resource enables you to group Jira Service Management customers together. Use it to create and delete organizations, and add and remove customers from them. |
request | This resource represents the customer requests in your service desks. Use it to create new requests and update request details, such as attachments and comments as well as take actions to update request status or review SLA performance. |
requesttype | This resource enables a list of customer request types, a way to categorize requests in a service desk, to be obtained. |
servicedesk | This resource represents a service desk. Use it to retrieve the service desks in your Jira instance, managed the requests service desks can handle, manage the associated customers and organizations, and retrieve details of request queues. |