Skip to content

Get Started with the Axiom API

Axiom understands your resources and provides an API to ingest structured data logs, handle and manage your deployments. This is a REST-style API that uses JSON for serialization.

This page covers the basics for interacting with the Axiom API, plus instructions for ingesting data and notes on some commonly used endpoints.

If you would like to manage Axiom more completely via API, we recommend you use axiom-go.

Authentication

You can generate an Ingest Token/Personal Token in your Axiom user settings for manual authentication in shell scripts or commands that use the Axiom API.

Refer to the code sample below for an example of how to use this token in a curl request. All requests must use HTTPS.

API Tokens

Axiom has two types of API tokens;

  • Personal API Tokens.
  • Ingest Tokens.

Personal API Token

The personal token can be retrieved from the users profile page, all users have a Personal Token. With the Personal Token users can access the Axiom API programmatically for custom integrations, management setting, or for tools such as the Axiom CLI.

The personal access token grants access to all resources available to the user on his behalf.

Personal Access can be created under Profile or Settings > Profile > Personal Tokens.

Personal Token overview

Ingest Token

Ingest Tokens just allows ingestion into the datasets the token is configured for. Use ingest tokens to send data to one or more datasets. Ingest tokens do not allow control of your organization, they are only used to ingest events.

For security reasons it is advised to use an Ingest Token with minimal privileges only.

You can obtain the Ingest Token from the settings > Ingest Token of the Axiom deployment.

Ingest Token overview

Sending Events to Axiom API.

To send events directly to Axiom API. We have the Go API client for your convenience:

Ingesting data

POST /api/v1/ingest/

Individual events are ingested as an HTTP POST request.

Using curl command to ingest data

curl -X POST '$YOUR_AXIOM_URL/api/v1/ingest' \
  -H 'Authorization: Bearer $INGEST_TOKEN or $PERSONAL_TOKEN' \
  -H 'Content-Type: application/x-ndjson' \
  -d "{  \"description\": \"string\",  \"name\": \"string\",  \"scopes\": [    \"string\"  ]}"

Body Specification

The body of the POST should be a JSON encoded object containing key/value pairs. As an example, to report a GET request from the users /download path with a duration of 231ms and a response size of 3012.

{ "path": "/download", "method": "GET", "duration_ms": 231, "res_size_bytes": 3012 }'

Axiom supports ingestion of different data formats:

  • application/json
  • application/nd-json
  • text/csv

Examples

These examples sends an API event to Axiom. It is in the neil-cmc dataset.

Ingest Events using NDJSON

NDJSON consists of individual lines where each individual line is any valid JSON text and each line is delimited with a newline character. The NDJSON payload should have the scheme of {"id":1,"name":"Alice"} {"id":2,"name":"Bob"} {"id":3,"name":"Carol"}

Example Request using NDJSON

curl -X 'POST' '$YOUR_AXIOM_URL/api/v1/datasets/neil-cmc/ingest' \
  -H 'Authorization: Bearer $INGEST_TOKEN or $PERSONAL_TOKEN' \
  -H 'Content-Type: application/x-ndjson' -H 'x-axiom-org-id: axiom' \
  -d '{ "path": "/download", "method": "POST", "duration_ms": 231, "res_size_bytes": 3012, "endpoint":"/foo" }'

More examples

curl -X 'POST' '$YOUR_AXIOM_URL/api/v1/datasets/neil-cmc/ingest' \
  -H 'Authorization: Bearer $INGEST_TOKEN or $PERSONAL_TOKEN' \
  -H 'Content-Type: application/x-ndjson' -H 'x-axiom-org-id: axiom' \
  -d '{"container": {"image": "front:master.0326.5","name": "tunnel-front"},"labels": {"component": "tunnel","pod-template-hash": "75f5666499"},"namespace": "kube-system","node": {"name": "32068356-vmss000002"},"pod": {"name": "fnxln","uid": "f0bdea4e57"},"replicaset": {"name": "75f5666499"}}}'

Example Response

A successful POST Request returns a 200 response code JSON with details

Ingest Events using JSON

The following example request contains grouped events. The structure of the JSON payload should have the scheme of [ { "labels": { "key1": "value1", "key2": "value12" } }, ] in which the array comprises of one or more JSON objects describing Events.

Example Request using JSON

curl -X 'POST' '$YOUR_AXIOM_URL/api/v1/datasets/neil-cmc/ingest' \
  -H 'Authorization: Bearer $INGEST_TOKEN' \
  -H 'Content-Type: application/json' -H 'x-axiom-org-id: axiom' \
  -d '[
        {
          "time":"2021-23-04302:11:23.222Z",
          "data":{"key1":"value1","key2":"value2"}
        },
        {
          "data":{"key3":"value3"},
          "labels":{"key4":"value4"}
        }
      ]'

Grouping Events with different Labels

You can also group events with different labels into the same request as shown below:

curl -X 'POST' '$YOUR_AXIOM_URL/api/v1/datasets/neil-cmc/ingest' \
  -H 'Authorization: Bearer $INGEST_TOKEN or $PERSONAL_TOKEN' \
  -H 'Content-Type: application/json' -H 'x-axiom-org-id: axiom' \
  -d '[
  {
    "labels": {
      "author": "System1",
      "model": "whip.log"
    },
    "events": [
      {
        "timestamp": "2020-05-04T11:00:00+06:00",
        "elements": {
          "foo": "bar"
        }
      },
      {
        "timestamp": "2020-05-04T12:00:01+03:00",
        "attributes": {
          "status": "202",
          "address": "/src.php"
        }
      }
    ]
  },
  {
    "labels": {
      "author": "System2",
      "model": "whip.log"
    },
    "events": [
      {
        "timestamp": "2020-05-04T13:00:02+02:00",
        "attributes": {
          "key2": "value2"
        }
      }
    ]
  },
  {
    "labels": {
      "author": "System3",
      "model": "whip.log"
    },
    "events": [
      {
        "timestamp": "2020-05-04T14:00:03+02:00",
        "attributes": {
          "key3": "value3",
          "status": "200"
        }
      }
    ]
  }
]'

Example Response

A successful POST Request returns a 200 response code JSON with details

Ingest Events using CSV

The following example request contains events. The structure of the CSV payload uses a comma to separate values ['value1', 'value2', 'value3'].

Example Request using CSV

curl -X 'POST' '$YOUR_AXIOM_URL/api/v1/datasets/neil-cmc/ingest' \
  -H 'Authorization: Bearer $INGEST_TOKEN or $PERSONAL_TOKEN' \
  -H 'Content-Type: text/csv' -H 'x-axiom-org-id: axiom' \
  -d '['name', 'area', 'country_code2', 'country_code3']'

Example Response

A successful POST Request returns a 200 response code JSON with details

Supported data types:

  • Strings
  • Numbers
  • Arrays of objects
  • Booleans

Datasets name are usually case sensitive, Dataset names must be between 1-128 characters, and may only contain ASCII alphanumeric characters and the '-' character.