• Alerts
  • Audit Logs
  • Contacts
  • Custom user roles
  • Escalations
  • Forwarding rules
  • Heartbeats
  • Integrations
  • Integration actions
  • Integration outgoing filters
  • Maintenances
  • Notification rules
  • Notification rule steps
  • Routing rules
  • Schedules
  • Schedule on-calls
  • Schedule overrides
  • Schedule rotations
  • Schedule timelines
  • Syncs
  • Sync actions
  • Sync action groups
Cloud
Jira Service Management ops / Reference / REST API

About

Postman Collection
OpenAPI

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

Jira Cloud Platform APIs

Jira Service Management operations, an integral part of Jira Service Management, is designed to optimize the management of your team's operations. Jira Service Management is built upon the Jira platform. As such, in Jira Service Management you have access to the Jira platform REST APIs.

Permissions and roles

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.

To use the Operations API, users must obtain either Global or Team roles depending on specific domain requirements.

Global Roles

Team Roles

Authentication

Authentication for REST API requests

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

Status codes and responses

  • 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 schedule has been successfully removed, but there's no additional content to display as a result.
  • Status 400 Returned if the request was invalid.
  • Status 401 Returned if the API token is not valid. Resolve this by validating the API token and reissuing the call.
  • Status 402 Returned if the client must pay to access the requested resource.
  • 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 Schedule exists for a passed ID.
  • Status 409 Returned when a conflict is identified with the request. This typically happens when the request tries to create an entity that already exists.
  • Status 422 Returned when the server understands the content type of the request entity, but the server was unable to process the contained instructions.
  • Status 429 Returned when the number of requests has exceeded the rate limit.

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

1
2
{
 "errors": [
       {
       "title": "Actual reason why user was not found",
     },
     {
       ...
     }
  ]
}

URL format

The Jira Service Management operations REST API uses a consistent URL pattern to access different resources. The general format is as follows:

1
2
https://api.atlassian.com/jsm/ops/api/{cloudId}/{version}/{domain}
  • {cloudId} represents the unique identifier for your cloud instance.
  • {version} is the version of the API you want to access. Currently, only version 1 ('v1') is available.
  • {domain} is the specific domain of the API you want to access. Examples include 'schedule', 'team', 'alert', 'user', among others. The exact domain will depend on the specific area of the API you wish to access.

An example of a fully constructed URL might look like this: https://api.atlassian.com/jsm/ops/api/{cloudId}/v1/schedules/{scheduleId}. This URL accesses the 'schedule' domain of the API for retrieving a schedule based on its id.

Date and time format

The Jira Service Management operations REST API follows the ISO 8601 standard for representing dates and times. This consistent string format, such as '2023-12-15T15:20:25+00:00', is used across all API endpoints. In this format, '2023-12-15' denotes the date (year-month-day), 'T' is a delimiter that separates the date from the time, '15:20:25' represents the time (hours:minutes:seconds), and '+00:00' indicates the timezone offset from Coordinated Universal Time (UTC).

Pagination

The Jira Service Management operations 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
2
https://api.atlassian.com/jsm/ops/api/{cloudId}/v1/{domain}?offset=0&size=10

Response

1
2
{
 "values" : [
    //list of DTOs
   ],
 "links": {
     "next": "https://api.atlassian.com/jsm/ops/api/{cloudId}/v1/{domain}?offset=1&size=10", //absence or null indicates it is the last page
     "prev": "",  //optional field
     "first": "", //optional field
     "last": ""   //optional field
   }
}

Expansion

To simplify API responses, the Jira Service Management operations 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=base to a request’s URI results in the inclusion of the base timeline details in the response of schedule timeline. The following URL would be used to get that information for the request:

1
2
https://api.atlassian.com/jsm/ops/api/{cloudId}/v1/schedules/{scheduleId}/timeline?expand=base

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

1
2
https://api.atlassian.com/jsm/ops/api/{cloudId}/v1/schedules/{scheduleId}/timeline?expand=base,forwarding,override

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 base, forwarding and override as expandable

1
2
{
 "startDate": "2023-12-24T21:00:00Z",
 "endDate": "2023-12-31T21:00:00Z",
 "finalTimeline": {
   "rotations": [
     // rotation DTOs
   ]
 },
 "baseTimeline": {
   "rotations": [
       // rotation DTOs
       ]
     },
 "_expands": [
       "base",
       "forwarding",
       "override"
     ]
}

Rate this page: