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.
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
Jira Service Management operations API supports the use of the basic authentication method. Basic auth for REST APIs for details.
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}
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}
.
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 2https://api.atlassian.com/jsm/ops/api/{cloudId}/{version}/{domain}
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 2https://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 2https://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 2https://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: