openapi: 3.0.3
info:
  title: Axiom Annotations Tokens API
  description: 'Axiom is a log management, event data, and observability platform. This OpenAPI document describes Axiom''s public REST API, which ingests logs, traces, and events into datasets and queries them with the Axiom Processing Language (APL). Axiom exposes two endpoint families: the v1 family (datasets, ingest, APL query, fields, current user) and the v2 family (annotations, monitors, notifiers, dashboards, virtual fields, starred queries, tokens, users). The default base domain is https://api.axiom.co for the US region; EU organizations use https://api.eu.axiom.co. All requests authenticate with a Bearer token (an API token or a Personal Access Token). Personal Access Tokens additionally require an x-axiom-org-id header. Endpoints marked x-endpoint-status "confirmed" were verified against Axiom''s published API reference; those marked "modeled" are represented from the documentation index and reference conventions and should be reconciled against the live reference.'
  version: '1.0'
  contact:
    name: Axiom
    url: https://axiom.co
  license:
    name: Proprietary
    url: https://axiom.co/terms
servers:
- url: https://api.axiom.co
  description: US region (default)
- url: https://api.eu.axiom.co
  description: EU region
security:
- bearerAuth: []
tags:
- name: Tokens
  description: Scoped API tokens used to authenticate requests.
paths:
  /v2/tokens:
    get:
      operationId: getTokens
      tags:
      - Tokens
      summary: List API tokens
      description: List the API tokens configured for the organization.
      x-endpoint-status: confirmed
      responses:
        '200':
          description: A list of API tokens.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Token'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createToken
      tags:
      - Tokens
      summary: Create an API token
      description: Create a scoped API token (basic ingest-only or advanced with query and management scopes). The token secret is returned once at creation.
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenCreateRequest'
      responses:
        '200':
          description: The created token, including its secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCreated'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/tokens/{id}:
    parameters:
    - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getToken
      tags:
      - Tokens
      summary: Get an API token
      x-endpoint-status: modeled
      responses:
        '200':
          description: The requested token (without secret).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: deleteToken
      tags:
      - Tokens
      summary: Delete an API token
      x-endpoint-status: modeled
      responses:
        '204':
          description: The token was deleted.
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/tokens/{id}/regenerate:
    parameters:
    - $ref: '#/components/parameters/ResourceId'
    post:
      operationId: regenerateToken
      tags:
      - Tokens
      summary: Regenerate an API token
      description: Regenerate the secret of an existing token.
      x-endpoint-status: modeled
      responses:
        '200':
          description: The token with a new secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCreated'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    TokenCreateRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        description:
          type: string
        scopes:
          type: array
          items:
            type: string
        datasetCapabilities:
          type: object
          additionalProperties: true
        expiresAt:
          type: string
          format: date-time
    Token:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        scopes:
          type: array
          items:
            type: string
        datasetCapabilities:
          type: object
          additionalProperties: true
        expiresAt:
          type: string
          format: date-time
    TokenCreated:
      allOf:
      - $ref: '#/components/schemas/Token'
      - type: object
        properties:
          token:
            type: string
            description: The token secret, returned only once.
    Error:
      type: object
      properties:
        message:
          type: string
          example: rate limit exceeded
  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The resource ID.
  responses:
    Forbidden:
      description: Authentication failed or the token lacks the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using an Axiom API token or Personal Access Token (PAT). PAT-authenticated requests must also send the x-axiom-org-id header.