• Linked alerts
  • Request status
  • Incident
  • Major Incident
  • Responders
Cloud
Incidents / Reference / REST API

About

Postman Collection
OpenAPI

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.

Version

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 Cloud Platform APIs

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

Authentication

Authentication for REST API requests

Jira Service Management Incident API supports the use of the basic authentication method. See Basic auth for REST APIs for details.

Authentication for Atlassian Connect apps

Support for Atlassian Connect app to interact with the Jira Service Management Incident API is currently unavailable.

Experimental methods

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.

Status codes and responses

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"
    }, 
    {
      ...
    }
  ]
}

Pagination

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.

Rate this page: