This is the reference for the Jira Service Management Incident REST API. The REST API is for developers who want to integrate JSM Incident with other applications or administrators that want to automate their workflows and processes.

This documentation is for version 1 of the Jira Service Management Incident REST API, which is the latest version but is in beta.

However, these new features are under development and may change.

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

Forge apps

For Forge apps, the following JSM Incident scopes are used when authenticating with Jira Cloud platform:

read:incident:jira-service-management

write:incident:jira-service-management

See Add scopes to call an JSM Incident REST API for more details.

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

/jsm/incidents/cloudId/<cloudId>/v1/incidents/<issueID>

For example, /jsm/incidents/cloudId/35273b54-3f06-40d2-880f-dd28cf8daafa/v1/incidents/10014

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. See Security for Connect apps for details.

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

https://<site-url>/jsm/incidents/cloudId/<cloudId>/v1/incidents/<issueID>

For example, https://your-domain.atlassian.net/jsm/incidents/cloudId/35273b54-3f06-40d2-880f-dd28cf8daafa/v1/incidents/10014

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). See OAuth 2.0 (3LO) apps for details.

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

https://api.atlassian.com/ex/jira/incidents/cloudId/<cloudId>/v1/incidents/<issueID>

For example, https://api.atlassian.com/ex/jira/incidents/cloudId/35273b54-3f06-40d2-880f-dd28cf8daafa/v1/incidents/10014

Ad-hoc API calls

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

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

https://<site-url>/jsm/incidents/cloudId/<cloudId>/v1/incidents/<issueID>

For example, https://your-domain.atlassian.net/jsm/incidents/cloudId/35273b54-3f06-40d2-880f-dd28cf8daafa/v1/incidents/10014

Methods marked as EXPERIMENTAL may change without notice. To use experimental methods, you must include the X-ExperimentalApi: opt-in header in your requests. This header indicates that you are opting into the experimental preview. Once a resource or method moves out of the experimental phase, 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.

Jira Service Management Incident API uses the standard HTTP status codes.

• STATUS 200 Returned if the requested content (GET) is returned or content is updated (POST).

• STATUS 201 Returned if new records are created (POST).

• STATUS 202 Returned if update or create operations on new or existing records are accepted to be processed asynchronously (PUT or POST).

• STATUS 204 Returned where the request has been successfully processed, the outcome is as expected. For example, the request to delete an Incident, and Incident is successfully deleted .

• STATUS 400 Returned if the request was invalid.

• 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 (object) is not found, for example, no Incident exists for the given Issue 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.

Operations that return an error status code may also return a response body containing details of the error or errors. The schema for the response body is shown below:

1
2
{
  "errors": [
    {
      "code": "USER_NOT_FOUND",
      "title": "Actual reason why user was not found",
      "detail": "Optional detail of the error"
    }, 
    {
      ...
    }
  ]
}

The JSM Incident 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 paginated API, the response will wrap the returned values in a JSON object with paging metadata, as follows:

Request

1
2
http://host:port/context/rest/api-name/resource-name?startKey=<cursor_of_resource>

Response

1
2
{
    "startKey" : <cursor_of_the_first_resouce_in_next_page>,
    "values": [
        { /* result 0 */ },
        { /* result 1 */ },
        { /* result 2 */ }
        { /* result 3 */ }
        { /* result 4 */ }
        { /* result 5 */ }
        { /* result 6 */ }
    ]
}

Where:

• startKey is the cursor to the first item on the next page of results. If next page does not exist then the startKey will be null.

The page limit set for each resource’s method are an implementation detail and may change in future.