Run Axiom Processing Language (APL) queries across one or more datasets. POST an APL query with optional start/end times and receive tabular or legacy results. A legacy per-dataset structured query endpoint is also supported.
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: '#/
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/axiom-co/refs/heads/main/openapi/axiom-co-openapi.yml