openapi: 3.0.3
info:
  title: Axiom 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: Ingest
    description: Send logs, traces, and events into a dataset.
  - name: Query
    description: Run APL queries across datasets.
  - name: Datasets
    description: Manage the datasets that store ingested event data.
  - name: Fields
    description: Inspect and annotate dataset fields.
  - name: Annotations
    description: Mark deployments, incidents, and events on charts.
  - name: Monitors
    description: APL-backed alert monitors.
  - name: Notifiers
    description: Notification channels monitors dispatch through.
  - name: Dashboards
    description: Collections of charts and visualizations.
  - name: Virtual Fields
    description: Derived fields computed from an APL expression at query time.
  - name: Starred Queries
    description: Saved, shareable APL queries.
  - name: Tokens
    description: Scoped API tokens used to authenticate requests.
  - name: Users
    description: Current user and organization members.
  - name: Organizations
    description: Organization-level settings.
paths:
  /v1/datasets:
    get:
      operationId: getDatasets
      tags:
        - Datasets
      summary: List datasets
      description: Retrieve the list of datasets in the organization.
      x-endpoint-status: confirmed
      responses:
        '200':
          description: A list of datasets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dataset'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createDataset
      tags:
        - Datasets
      summary: Create a dataset
      description: Create a new dataset to store ingested events.
      x-endpoint-status: confirmed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetCreateRequest'
      responses:
        '200':
          description: The created dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/datasets/{id}:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      operationId: getDataset
      tags:
        - Datasets
      summary: Get a dataset
      description: Retrieve a single dataset by ID or name.
      x-endpoint-status: confirmed
      responses:
        '200':
          description: The requested dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      operationId: updateDataset
      tags:
        - Datasets
      summary: Update a dataset
      description: Update a dataset's description.
      x-endpoint-status: confirmed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetUpdateRequest'
      responses:
        '200':
          description: The updated dataset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: deleteDataset
      tags:
        - Datasets
      summary: Delete a dataset
      description: Permanently delete a dataset and its data.
      x-endpoint-status: confirmed
      responses:
        '204':
          description: The dataset was deleted.
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/datasets/{id}/trim:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    post:
      operationId: trimDataset
      tags:
        - Datasets
      summary: Trim a dataset
      description: Delete data older than a given duration from the dataset.
      x-endpoint-status: confirmed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                maxDuration:
                  type: string
                  description: Retention duration to keep, e.g. "30d".
                  example: 30d
      responses:
        '200':
          description: Trim result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  numDeleted:
                    type: integer
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/datasets/{id}/ingest:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    post:
      operationId: ingestIntoDataset
      tags:
        - Ingest
      summary: Ingest data into a dataset
      description: >-
        Send events into a dataset. Accepts a JSON array of event objects
        (application/json), newline-delimited JSON (application/x-ndjson), or
        CSV (text/csv). Optional query parameters control timestamp parsing.
      x-endpoint-status: confirmed
      parameters:
        - name: timestamp-field
          in: query
          required: false
          schema:
            type: string
          description: Name of the field holding the event timestamp.
        - name: timestamp-format
          in: query
          required: false
          schema:
            type: string
          description: Format of the timestamp field.
        - name: Content-Encoding
          in: header
          required: false
          schema:
            type: string
            enum: [gzip, zstd]
          description: Optional compression of the request body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                additionalProperties: true
          application/x-ndjson:
            schema:
              type: string
          text/csv:
            schema:
              type: string
      responses:
        '200':
          description: Ingest status summary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestStatus'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/datasets/{id}/query:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    post:
      operationId: queryDataset
      tags:
        - Query
      summary: Run a query (legacy)
      description: >-
        Run a structured (legacy) query against a single dataset. Prefer the
        APL query endpoint for new integrations.
      x-endpoint-status: confirmed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Query result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/datasets/_apl:
    post:
      operationId: queryApl
      tags:
        - Query
      summary: Run an APL query
      description: >-
        Run an Axiom Processing Language (APL) query across one or more
        datasets. The dataset(s) are named inside the APL statement itself.
      x-endpoint-status: confirmed
      parameters:
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [tabular, legacy]
            default: tabular
          description: Result serialization format.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AplQueryRequest'
      responses:
        '200':
          description: APL query result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResult'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/datasets/{id}/fields:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      operationId: getFieldsForDataset
      tags:
        - Fields
      summary: List fields for a dataset
      description: List the discovered fields (schema) for a dataset.
      x-endpoint-status: modeled
      responses:
        '200':
          description: A list of fields.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Field'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/datasets/{id}/fields/{fieldName}:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
      - name: fieldName
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getFieldForDataset
      tags:
        - Fields
      summary: Get a field
      description: Retrieve metadata for a single field of a dataset.
      x-endpoint-status: modeled
      responses:
        '200':
          description: The requested field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      operationId: updateFieldForDataset
      tags:
        - Fields
      summary: Update a field
      description: Update per-field metadata such as description, unit, or hidden state.
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Field'
      responses:
        '200':
          description: The updated field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/user:
    get:
      operationId: getCurrentUserV1
      tags:
        - Users
      summary: Get the current user (v1)
      description: Retrieve the user associated with the authenticating token.
      x-endpoint-status: modeled
      responses:
        '200':
          description: The current user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/orgs:
    get:
      operationId: getOrgs
      tags:
        - Organizations
      summary: List organizations
      description: List the organizations the caller belongs to.
      x-endpoint-status: modeled
      responses:
        '200':
          description: A list of organizations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Organization'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/orgs/{orgId}:
    parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getOrg
      tags:
        - Organizations
      summary: Get an organization
      description: Retrieve a single organization by ID.
      x-endpoint-status: modeled
      responses:
        '200':
          description: The requested organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      operationId: updateOrg
      tags:
        - Organizations
      summary: Update an organization
      description: Update organization-level configuration.
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Organization'
      responses:
        '200':
          description: The updated organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/annotations:
    get:
      operationId: getAnnotations
      tags:
        - Annotations
      summary: List annotations
      description: >-
        List annotations, optionally filtered by dataset names and a start/end
        time range.
      x-endpoint-status: confirmed
      parameters:
        - name: datasets
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated dataset names to filter by.
        - name: start
          in: query
          required: false
          schema:
            type: string
            format: date-time
        - name: end
          in: query
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: A list of annotations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Annotation'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createAnnotation
      tags:
        - Annotations
      summary: Create an annotation
      description: Create an annotation scoped to one or more datasets and a time.
      x-endpoint-status: confirmed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Annotation'
      responses:
        '200':
          description: The created annotation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/annotations/{id}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getAnnotation
      tags:
        - Annotations
      summary: Get an annotation
      x-endpoint-status: modeled
      responses:
        '200':
          description: The requested annotation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      operationId: updateAnnotation
      tags:
        - Annotations
      summary: Update an annotation
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Annotation'
      responses:
        '200':
          description: The updated annotation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: deleteAnnotation
      tags:
        - Annotations
      summary: Delete an annotation
      x-endpoint-status: modeled
      responses:
        '204':
          description: The annotation was deleted.
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/monitors:
    get:
      operationId: getMonitors
      tags:
        - Monitors
      summary: List monitors
      description: List all configured monitors.
      x-endpoint-status: confirmed
      responses:
        '200':
          description: A list of monitors.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Monitor'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createMonitor
      tags:
        - Monitors
      summary: Create a monitor
      description: Create an APL-backed threshold or match monitor.
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Monitor'
      responses:
        '200':
          description: The created monitor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/monitors/{id}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getMonitor
      tags:
        - Monitors
      summary: Get a monitor
      x-endpoint-status: modeled
      responses:
        '200':
          description: The requested monitor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      operationId: updateMonitor
      tags:
        - Monitors
      summary: Update a monitor
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Monitor'
      responses:
        '200':
          description: The updated monitor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Monitor'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: deleteMonitor
      tags:
        - Monitors
      summary: Delete a monitor
      x-endpoint-status: modeled
      responses:
        '204':
          description: The monitor was deleted.
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/monitors/{id}/history:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getMonitorHistory
      tags:
        - Monitors
      summary: Get monitor run history
      description: Retrieve the run/evaluation history of a monitor.
      x-endpoint-status: modeled
      responses:
        '200':
          description: Monitor history entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/notifiers:
    get:
      operationId: getNotifiers
      tags:
        - Notifiers
      summary: List notifiers
      description: >-
        List all configured notifiers. Requires the notifiers|read scope.
      x-endpoint-status: confirmed
      responses:
        '200':
          description: A list of notifiers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Notifier'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createNotifier
      tags:
        - Notifiers
      summary: Create a notifier
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Notifier'
      responses:
        '200':
          description: The created notifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notifier'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/notifiers/{id}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getNotifier
      tags:
        - Notifiers
      summary: Get a notifier
      x-endpoint-status: modeled
      responses:
        '200':
          description: The requested notifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notifier'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      operationId: updateNotifier
      tags:
        - Notifiers
      summary: Update a notifier
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Notifier'
      responses:
        '200':
          description: The updated notifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notifier'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: deleteNotifier
      tags:
        - Notifiers
      summary: Delete a notifier
      x-endpoint-status: modeled
      responses:
        '204':
          description: The notifier was deleted.
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/dashboards:
    get:
      operationId: getDashboards
      tags:
        - Dashboards
      summary: List dashboards
      description: >-
        List dashboards visible to the caller. Supports limit (default 100,
        max 1000) and offset (default 0) pagination.
      x-endpoint-status: confirmed
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
            maximum: 1000
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: A list of dashboards.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dashboard'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createDashboard
      tags:
        - Dashboards
      summary: Create a dashboard
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Dashboard'
      responses:
        '200':
          description: The created dashboard.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dashboard'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/dashboards/{id}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getDashboard
      tags:
        - Dashboards
      summary: Get a dashboard
      x-endpoint-status: modeled
      responses:
        '200':
          description: The requested dashboard.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dashboard'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      operationId: updateDashboard
      tags:
        - Dashboards
      summary: Update a dashboard
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Dashboard'
      responses:
        '200':
          description: The updated dashboard.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dashboard'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: deleteDashboard
      tags:
        - Dashboards
      summary: Delete a dashboard
      x-endpoint-status: modeled
      responses:
        '204':
          description: The dashboard was deleted.
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/vfields:
    get:
      operationId: getVirtualFields
      tags:
        - Virtual Fields
      summary: List virtual fields
      description: List all virtual fields for the specified dataset.
      x-endpoint-status: confirmed
      parameters:
        - name: dataset
          in: query
          required: true
          schema:
            type: string
          description: The dataset to list virtual fields for.
      responses:
        '200':
          description: A list of virtual fields.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VirtualField'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createVirtualField
      tags:
        - Virtual Fields
      summary: Create a virtual field
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualField'
      responses:
        '200':
          description: The created virtual field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualField'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/vfields/{id}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getVirtualField
      tags:
        - Virtual Fields
      summary: Get a virtual field
      x-endpoint-status: modeled
      responses:
        '200':
          description: The requested virtual field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualField'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      operationId: updateVirtualField
      tags:
        - Virtual Fields
      summary: Update a virtual field
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualField'
      responses:
        '200':
          description: The updated virtual field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualField'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: deleteVirtualField
      tags:
        - Virtual Fields
      summary: Delete a virtual field
      x-endpoint-status: modeled
      responses:
        '204':
          description: The virtual field was deleted.
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/starred:
    get:
      operationId: getStarredQueries
      tags:
        - Starred Queries
      summary: List starred queries
      description: List saved (starred) APL queries.
      x-endpoint-status: modeled
      parameters:
        - name: dataset
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A list of starred queries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StarredQuery'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createStarredQuery
      tags:
        - Starred Queries
      summary: Create a starred query
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StarredQuery'
      responses:
        '200':
          description: The created starred query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StarredQuery'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/starred/{id}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getStarredQuery
      tags:
        - Starred Queries
      summary: Get a starred query
      x-endpoint-status: modeled
      responses:
        '200':
          description: The requested starred query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StarredQuery'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      operationId: updateStarredQuery
      tags:
        - Starred Queries
      summary: Update a starred query
      x-endpoint-status: modeled
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StarredQuery'
      responses:
        '200':
          description: The updated starred query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StarredQuery'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: deleteStarredQuery
      tags:
        - Starred Queries
      summary: Delete a starred query
      x-endpoint-status: modeled
      responses:
        '204':
          description: The starred query was deleted.
        '403':
          $ref: '#/components/responses/Forbidden'
  /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'
  /v2/user:
    get:
      operationId: getCurrentUser
      tags:
        - Users
      summary: Get the current user
      description: Retrieve the user associated with the authenticating token.
      x-endpoint-status: modeled
      responses:
        '200':
          description: The current user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/users:
    get:
      operationId: getUsers
      tags:
        - Users
      summary: List organization members
      description: List the members of the organization.
      x-endpoint-status: modeled
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/users/{id}:
    parameters:
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getUser
      tags:
        - Users
      summary: Get a user
      x-endpoint-status: modeled
      responses:
        '200':
          description: The requested user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      operationId: removeUserFromOrg
      tags:
        - Users
      summary: Remove a member from the organization
      x-endpoint-status: modeled
      responses:
        '204':
          description: The member was removed.
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  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.
  parameters:
    DatasetId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The dataset ID or name.
    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'
    RateLimited:
      description: Rate limit exceeded.
      headers:
        X-RateLimit-Scope:
          schema:
            type: string
          description: Whether the limit is applied at the user or organization scope.
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests allowed in the current window.
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining in the current window.
        X-RateLimit-Reset:
          schema:
            type: integer
          description: UTC epoch seconds when the window resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          example: rate limit exceeded
    Dataset:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        who:
          type: string
        created:
          type: string
          format: date-time
    DatasetCreateRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
    DatasetUpdateRequest:
      type: object
      properties:
        description:
          type: string
    IngestStatus:
      type: object
      properties:
        ingested:
          type: integer
        failed:
          type: integer
        processedBytes:
          type: integer
        blocksCreated:
          type: integer
        walLength:
          type: integer
        failures:
          type: array
          items:
            type: object
            additionalProperties: true
    AplQueryRequest:
      type: object
      required:
        - apl
      properties:
        apl:
          type: string
          description: The APL query text. Dataset(s) are referenced inside the query.
          example: "['my-dataset'] | where status == 500 | count"
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
    QueryResult:
      type: object
      properties:
        status:
          type: object
          additionalProperties: true
        tables:
          type: array
          items:
            type: object
            additionalProperties: true
        matches:
          type: array
          items:
            type: object
            additionalProperties: true
    Field:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
        description:
          type: string
        unit:
          type: string
        hidden:
          type: boolean
    Annotation:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        datasets:
          type: array
          items:
            type: string
        title:
          type: string
        description:
          type: string
        url:
          type: string
        time:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
    Monitor:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        type:
          type: string
          description: Monitor type, e.g. Threshold or MatchEvent.
        aplQuery:
          type: string
        threshold:
          type: number
        operator:
          type: string
        intervalMinutes:
          type: integer
        notifierIds:
          type: array
          items:
            type: string
        disabled:
          type: boolean
    Notifier:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          description: Channel type, e.g. email, slack, pagerduty, webhook.
        properties:
          type: object
          additionalProperties: true
    Dashboard:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        charts:
          type: array
          items:
            type: object
            additionalProperties: true
        layout:
          type: array
          items:
            type: object
            additionalProperties: true
    VirtualField:
      type: object
      properties:
        id:
          type: string
        dataset:
          type: string
        name:
          type: string
        expression:
          type: string
          description: The APL expression evaluated at query time.
        description:
          type: string
        type:
          type: string
    StarredQuery:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        dataset:
          type: string
        kind:
          type: string
        query:
          type: object
          additionalProperties: true
    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
    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
    TokenCreated:
      allOf:
        - $ref: '#/components/schemas/Token'
        - type: object
          properties:
            token:
              type: string
              description: The token secret, returned only once.
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        role:
          type: string
    Organization:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        plan:
          type: string
        planCreated:
          type: string
          format: date-time