Permissions control the level of a user's access to the Compass instance, while roles are how the permissions are assigned to individual users. For detailed information on roles and permissions, see Permissions overview. 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.

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

• 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 Compass operations REST API uses a consistent URL pattern to access different resources. The general format is as follows:

1
2
  https://api.atlassian.com/compass/cloud/{cloudId}/ops/{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/compass/cloud/{cloudId}/ops/v1/schedules/{scheduleId}. This URL accesses the 'schedule' domain of the API for retrieving a schedule based on its id.

The Compass 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 Compass 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/compass/cloud/{cloudId}/ops/v1/{domain}?offset=0&size=10

Response

1
2
{
  "values" : [
    //list of DTOs
  ],
  "links": {
    "next": "https://api.atlassian.com/compass/cloud/{cloudId}/ops/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 Compass 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/compass/cloud/{cloudId}/ops/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/compass/cloud/{cloudId}/ops/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"
  ]
}