This is the reference for the Compass REST API. The REST API enables you to interact with Compass programmatically. Use this API for scripting interactions with Compass and sending data from external tools. This page documents the REST resources available in Compass, including the HTTP response codes and example requests and responses.

In addition to the Compass REST API, you can use our Atlassian platform GraphQL API to use many more Compass features.

This documentation is for version 1 of the Compass REST API.

The REST API supports basic auth.

Get an API token

Basic auth requires API tokens. You generate an API token for your Atlassian account and use it to authenticate anywhere where you would have used a password. This authentication enhances security because:

• you're not saving your primary account password outside of where you authenticate
• you can quickly revoke individual API tokens on a per-use basis
• API tokens allow you to authenticate even if your Atlassian Cloud organization has two-factor authentication or SAML enabled

See the Atlassian Cloud Support API tokens article to discover how to generate an API token.

Simple example

Most client software provides a simple mechanism for supplying a user name (in our case, the email address) and API token that the client uses to build the required authentication headers. For example, you can specify the --user argument in cURL as follows:

1
2
curl --request POST \
  --url 'https://your-domain.atlassian.net/gateway/api/compass/v1/metrics' \
  --user 'email@example.com:<api_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "metricSourceId": "<string>",
  "value": 32,
  "timestamp": "<string>"
}'

Supply basic auth headers

You can construct and send basic auth headers, including a base64-encoded string that contains your Atlassian account email and API token.

To use basic auth headers, perform the following steps:

1. Generate an API Token for your Atlassian Account: https://id.atlassian.com/manage/api-tokens
2. Build a string of the form your_email@domain.com:your_user_api_token
3. You need to encode your authorization credentials to base64. There are online tools (such as, https://www.base64encode.net/) that you can use to create your base64 encoded string. For example, your_email@domain.com:your_user_api_token base64 encoded is eW91cl9lbWFpbEBkb21haW4uY29tOnlvdXJfdXNlcl9hcGlfdG9rZW4=
4. Supply an Authorization header with content Basic followed by the encoded string. Example: Authorization: Basic eW91cl9lbWFpbEBkb21haW4uY29tOnlvdXJfdXNlcl9hcGlfdG9rZW4=

If you are making calls directly against the REST API, authorization is based on the user used in the authentication process.

The Compass REST API uses the standard HTTP status codes.

Responses that return an error status code also return a response body, similar to this:

1
2
{
  "errors": [
    {
      "type": "FORMAT_INVALID",
      "message": "Field [value] is invalid."
    }
  ]
}