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 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.

• 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 desk users.

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

Global Roles

• Admin - They are responsible for overall administration, including managing global settings, user accounts, and security settings. Give users admin permissions
• User - This standard role allows users to update their own information. Additionally, this role can be extended through the definition of custom roles. For more details, please refer to

Team Roles

• Team Admin - Members of your team that take this role can manage any kind of settings, configuration (schedule configuration, integration setup, etc.), and other users in the team. Learn more about Team Roles
• Team Member - Team members can only access the configurations that they're part of, and they can only access the alerts that they have permission for.

Authentication for REST API requests

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

Authentication for Forge apps

For Forge apps, REST API scopes are used when authenticating with Jira Service Management operations.

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

/jsm/ops/api/{api}

Authentication for other integrations

For integrations that are not Forge, 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/{customerId}/jsm/ops/api/{api} If you are copying the examples in this document,you'll need to change the URLs from https://api.atlassian.com/jsm/ops/api/{cloudId}/{api} to https://api.atlassian.com/ex/jira/{customerId}/jsm/ops/api/{api}.

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

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.

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).

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
   }
}

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"
     ]
}