Atlassian Compass Metrics API

openapi: 3.2.0
info:
  title: Compass REST Metrics API
  version: '1'
  description: This resource represents metrics. Use this resource to send metric values into a component's metric source.
servers:
- url: https://your-domain.atlassian.net/gateway/api
security:
- basicAuth: []
tags:
- name: Metrics
  description: This resource represents metrics. Use this resource to send metric values into a component's metric source.
paths:
  /compass/v1/metrics:
    post:
      tags:
      - Metrics
      summary: Send metric value
      description: Sends a metric value into a metric source for a component. This API is rate limited. Only 100 requests per user per minute are allowed.
      operationId: insertMetricValue
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/InsertMetricByMetricDefinitionRequestDto'
              - $ref: '#/components/schemas/InsertMetricByMetricSourceRequestDto'
        required: true
      responses:
        '200':
          description: Returned if the request is successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsertMetricResponseDto'
        '400':
          description: Returned if the request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '403':
          description: Returned if the user does not have permission to insert metrics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '404':
          description: Returned if the metric source, metric definition or component is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDto'
        '429':
          description: Returned if the request exceeds the rate limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsertMetricResponseDto'
components:
  schemas:
    InsertMetricByMetricDefinitionRequestDto:
      allOf:
      - $ref: '#/components/schemas/InsertMetricRequestDto'
      - type: object
        properties:
          metricDefinitionId:
            type: string
            description: The metric definition ID corresponding to the metric source to send the value into.
          componentId:
            type: string
            description: The component ID corresponding to the metric source to send the value into.
          timestamp:
            type:
            - string
            - 'null'
            format: date-time
            description: The time the metric value was collected.
          annotation:
            type:
            - string
            - 'null'
            description: The ADF annotation attached to a metric value.
      required:
      - componentId
      - metricDefinitionId
      - value
    ErrorResponseDto:
      type: object
      description: A list of errors that occurred.
      properties:
        errors:
          type:
          - array
          - 'null'
          description: A list of errors that occurred.
          items:
            $ref: '#/components/schemas/ErrorDto'
    InsertMetricRequestDto:
      type: object
      properties:
        title:
          type: string
          description: The title of the metric value source. The title of the metric source being inserted into will be updated to match this value.If this property is not provided, the existing value on the metric source will not be updated.
        value:
          type: number
          format: double
          description: The metric value to send.
        annotation:
          type: string
          description: The ADF annotation attached to a metric value.
        timestamp:
          type: string
          format: date-time
          description: The time the metric value was collected.
        url:
          type: string
          description: The url of the metric value source. The url of the metric source being inserted into will be updated to match this value. If this property is not provided, the existing value on the metric source will not be updated.
      required:
      - value
    InsertMetricResponseDto:
      type: object
      description: The metric value that was sent into the metric source.
      properties:
        metricSourceId:
          type: string
          description: The ID of the metric source.
        value:
          type: number
          format: double
          description: The value of the metric.
        timestamp:
          type: string
          format: date-time
          description: The time the metric value was collected.
        annotation:
          type:
          - string
          - 'null'
          description: The metric value annotation.
      required:
      - metricSourceId
      - timestamp
      - value
    ErrorDto:
      type: object
      description: An error.
      properties:
        type:
          type:
          - string
          - 'null'
          description: A code representing the type of error.
        message:
          type:
          - string
          - 'null'
          description: A message describing the error.
    InsertMetricByMetricSourceRequestDto:
      allOf:
      - $ref: '#/components/schemas/InsertMetricRequestDto'
      - type: object
        properties:
          metricSourceId:
            type: string
            description: The ID of the metric source to send the value into.
          timestamp:
            type:
            - string
            - 'null'
            format: date-time
            description: The time the metric value was collected.
          annotation:
            type:
            - string
            - 'null'
            description: The ADF annotation attached to a metric value.
      required:
      - metricSourceId
      - value
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-atlassian-narrative:
  documents:
  - title: About
    anchor: about
    body: 'This is the reference for the Compass REST API.

      The REST API enables you to interact with [Compass](/cloud/compass/overview/what-is-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](/cloud/compass/graphql/) to use many more Compass features.'
  - title: Version
    anchor: version
    body: This documentation is for version 1 of the Compass REST API.
  - title: Authentication
    anchor: authentication
    body: "The REST API supports basic auth.\n\n### Get an API token\nBasic 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:\n\n* you're not saving your primary account password outside of where you authenticate\n* you can quickly revoke individual API tokens on a per-use basis\n* API tokens allow you to authenticate even if your Atlassian Cloud organization has two-factor authentication or SAML enabled\n\nSee the Atlassian Cloud Support [API tokens](https://confluence.atlassian.com/x/Vo71Nw) article to discover how to generate an API token.\n\n### Simple example\nMost 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:\n\n```\ncurl --request POST \\\n  --url 'https://your-domain.atlassian.net/gateway/api/compass/v1/metrics' \\\n  --user 'email@example.com:<api_token>' \\\n  --header 'Accept: application/json' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n  \"metricSourceId\": \"<string>\",\n  \"value\": 32,\n  \"timestamp\": \"<string>\"\n}'\n```\n\n### Supply basic auth headers\nYou can construct and send basic auth headers, including a base64-encoded string that contains your Atlassian account email and API token.\n\nTo use basic auth headers, perform the following steps:\n\n1. Generate an API Token for your Atlassian Account: https://id.atlassian.com/manage/api-tokens\n1. Build a string of the form `your_email@domain.com:your_user_api_token`\n1. 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=`\n1. Supply an `Authorization` header with content `Basic` followed by the encoded string. Example: `Authorization: Basic eW91cl9lbWFpbEBkb21haW4uY29tOnlvdXJfdXNlcl9hcGlfdG9rZW4=`"
  - title: Authorization
    anchor: authorization
    body: If you are making calls directly against the REST API, authorization is based on the user used in the authentication process.
  - title: Status codes
    anchor: status-code
    body: "The Compass REST API uses the [standard HTTP status codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).\n\nResponses that return an error status code also return a response body, similar to this:\n```json\n{\n  \"errors\": [\n    {\n      \"type\": \"FORMAT_INVALID\",\n      \"message\": \"Field [value] is invalid.\"\n    }\n  ]\n}\n```"