Send data to Axiom using the Splunk HEC API

The HEC API is served from a dedicated host on your edge deployment: hec.AXIOM_DOMAIN. For example, if your edge deployment’s base domain is us-east-1.aws.edge.axiom.co, the HEC endpoint is https://hec.us-east-1.aws.edge.axiom.co.

Prerequisites#

• Create an Axiom account.
• Create a dataset in Axiom where you send your data.
• Create an API token in Axiom with permissions to ingest data to the dataset you have created.

Authentication#

Authenticate every request with an Axiom API token that has permission to ingest into the target dataset. The HEC API accepts the token in any of the following schemes:

Requests without a valid token are rejected with 401 Unauthorized (missing token) or 403 Forbidden (token not permitted for the dataset).

Choose the target dataset#

In Splunk, events are routed by index. Axiom maps the HEC index to an Axiom dataset and resolves it in the following order:

1. The index query parameter, for example ?index=DATASET_NAME.
2. The index field inside the event envelope.
3. The dataset the API token is scoped to, when the token grants ingest access to exactly one dataset.

If none of these resolve to a dataset, the request is rejected with HEC code 7 (Incorrect index).

Send events#

Send JSON events to /services/collector/event. The bare /services/collector path is an alias of the event endpoint. Each request body is one or more HEC event envelopes, which may be concatenated (newline-delimited or back-to-back).

curl -X POST 'https://hec.AXIOM_DOMAIN/services/collector/event?index=DATASET_NAME' \
    -H 'Authorization: Splunk API_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{"event": {"message": "hello from HEC", "severity": "INFO"}, "sourcetype": "httpevent"}'

A successful ingest returns 200 OK with the Splunk status body:

{"text": "Success", "code": 0}

Event envelope fields#

Axiom interprets the standard HEC envelope fields as follows:

Send raw events#

Send arbitrary payloads to /services/collector/raw. Metadata is supplied through query parameters rather than an envelope. Each line of a text/plain body becomes an event; JSON bodies are also accepted.

curl -X POST 'https://hec.AXIOM_DOMAIN/services/collector/raw?index=DATASET_NAME&sourcetype=mysourcetype&source=mysource&host=myhost' \
    -H 'Authorization: Splunk API_TOKEN' \
    -H 'Content-Type: text/plain' \
    --data-binary 'a raw log line
another raw log line'

Compressed payloads#

The HEC API accepts gzip-compressed request bodies. Set Content-Encoding: gzip and send the gzipped payload:

curl -X POST 'https://hec.AXIOM_DOMAIN/services/collector/event?index=DATASET_NAME' \
    -H 'Authorization: Splunk API_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Content-Encoding: gzip' \
    --data-binary @events.json.gz

Check service health#

GET /services/collector/health (and the versioned /services/collector/health/1.0) report whether the collector is accepting data. No authentication is required.

curl 'https://hec.AXIOM_DOMAIN/services/collector/health'

{"text": "HEC is healthy", "code": 17}

Response codes#

Responses follow the Splunk HEC convention: an HTTP status code plus a JSON body carrying a Splunk code.