Get started with Axiom API
This section explains how to send data to Axiom, query data, and manage resources using the Axiom API.
You can use the Axiom API (Application Programming Interface) to send data to Axiom, query data, and manage resources programmatically. This page covers the basics for interacting with the Axiom API.
Prerequisites
- Create an Axiom account.
- Create a dataset in Axiom where you send your data.
API basics
Axiom API follows the REST architectural style and uses JSON for serialization. You can send API requests to Axiom with curl or API tools such as Postman.
For example, the following curl command ingests data to an Axiom dataset:
For more information, see Send data to Axiom via API and Ingest data endpoint.
Base domain
The base domain of an API request depends on the endpoint:
-
Edge ingest and query endpoints: Use the base domain of your edge deployment for ingest (
/v1/ingest/{dataset-id}) and edge query endpoints (/v1/query/_apl,/v1/query/_mpl,/v1/query/batch, and/v1/query/metrics/info/*).Edge deployment Base domain for ingest and query US East 1 (AWS)us-east-1.aws.edge.axiom.coEU Central 1 (AWS)eu-central-1.aws.edge.axiom.coFor more information on edge deployments, see Edge deployments.
-
Splunk HEC endpoints: Prefix
hec.to the base domain of your edge deployment for/services/collector/*endpoints. For example,https://hec.us-east-1.aws.edge.axiom.co. For more information, see Send data using the Splunk HEC API. -
All other REST API endpoints: Use
https://api.axiom.co(for example, resource management endpoints under/v2).
Content type
Encode the body of API requests as JSON objects and set the Content-Type header to application/json. Unless otherwise specified, Axiom encodes all responses (including errors) as JSON objects.
Authentication
To prove that API requests come from you, include a token in your API requests. Axiom offers two types of tokens:
- API tokens let you control the actions that can be performed with the token. For example, you can specify that requests authenticated with a certain API token can only query data from a particular dataset.
- Personal access tokens (PATs) provide full control over your Axiom account. Requests authenticated with a PAT can perform every action you can perform in Axiom. When possible, use API tokens instead of PATs.
Edge ingest (/v1/ingest/{dataset-id}) and Splunk HEC (/services/collector/*) endpoints only support API tokens. Edge query endpoints (/v1/query/*) and core /v2 endpoints accept both API tokens and PATs.
If you use an API token for authentication, include the API token in the Authorization header:
If you use a PAT for authentication, include the PAT in the Authorization header and the organization ID in the X-Axiom-Org-Id header. For more information, see Determine org ID.
If a token is missing, invalid, or unsupported for the endpoint (including a PAT without X-Axiom-Org-Id on edge query), Axiom returns 401 Unauthorized. If you are authenticated but lack permission for the requested action, Axiom returns 403 Forbidden.
Data types
Below is a list of the types of data used within the Axiom API:
| Name | Definition | Example |
|---|---|---|
| ID | A unique value used to identify resources. | "io12h34io1h24i" |
| String | A sequence of characters used to represent text. | "string value" |
| Boolean | A type of two possible values representing true or false. | true |
| Integer | A number without decimals. | 4567 |
| Float | A number with decimals. | 15.67 |
| Map | A data structure with a list of values assigned to a unique key. | { "key": "value" } |
| List | A data structure with only a list of values separated by a comma. | ["value", 4567, 45.67] |