Manage datasets via API

Learn how to manage Axiom datasets via API.

This page explains how to manage datasets programmatically via the API.

Prerequisites

• Create an Axiom account.
• Create a dataset in Axiom where you send your data.

• Create an API token in Axiom with permissions to create, read, update, and delete datasets.
• In the code samples below, replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Create datasets

To create a dataset, send a POST request to the datasets endpoint. In the body of the request, specify the name and the description of the dataset. For example:

curl -X 'POST' 'https://AXIOM_DOMAIN/v2/datasets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer API_TOKEN' \
-d '{
    "description": "This is a test dataset.",
    "name": "test_dataset"
  }'

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

The example response contains the dataset ID that you can later use to access the dataset programmatically.

{
  "canWrite": true,
  "created": "2025-07-02T09:40:53.327Z",
  "description": "This is a test dataset.",
  "id": "test_dataset",
  "mapFields": null,
  "name": "test_dataset",
  "retentionDays": 0,
  "useRetentionPeriod": false,
  "who": ""
}

For more information, see the API reference.

Get information about datasets

Get information about all datasets

To get information about all the datasets in your Axiom organization, send a GET request to the datasets endpoint. For example:

curl -X 'GET' 'https://AXIOM_DOMAIN/v2/datasets' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer API_TOKEN'

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

The example response is a list of dataset objects. Each object contains a unique dataset ID that you can later use to access the dataset programmatically.

[
    {
        "canWrite": true,
        "created": "2025-05-26T09:39:47.909Z",
        "description": "This is a test dataset.",
        "id": "test_dataset1",
        "mapFields": null,
        "name": "test_dataset1",
        "retentionDays": 0,
        "useRetentionPeriod": false,
        "who": ""
    },
    {
        "canWrite": true,
        "created": "2025-07-02T09:40:53.327Z",
        "description": "This is another test dataset.",
        "id": "test_dataset2",
        "mapFields": null,
        "name": "test_dataset2",
        "retentionDays": 0,
        "useRetentionPeriod": false,
        "who": ""
    }
]

For more information, see the API reference.

Get information about specific dataset

To get information about a specific dataset, send a GET request to the datasets/DATASET_ID endpoint where DATASET_ID is the unique ID of the dataset. For example:

curl -X 'GET' 'https://AXIOM_DOMAIN/v2/datasets/test_dataset' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer API_TOKEN'

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Example response:

{
  "canWrite": true,
  "created": "2025-07-02T09:40:53.327Z",
  "description": "This is a test dataset.",
  "id": "test_dataset",
  "mapFields": null,
  "name": "test_dataset",
  "retentionDays": 0,
  "useRetentionPeriod": false,
  "who": ""
}

For more information, see the API reference.

Update datasets

To update a dataset, send a PUT request to the datasets/DATASET_ID endpoint where DATASET_ID is the unique ID of the dataset. In the body of the request, specify the properties you want to update. For example:

curl -X 'PUT' 'https://AXIOM_DOMAIN/v2/datasets/test_dataset' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer API_TOKEN' \
-d '{
    "description": "This is a production dataset."
  }'

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Example response:

{
  "canWrite": true,
  "created": "2025-07-02T09:40:53.327Z",
  "description": "This is a production dataset.",
  "id": "test_dataset",
  "mapFields": null,
  "name": "test_dataset",
  "retentionDays": 0,
  "useRetentionPeriod": false,
  "who": ""
}

For more information, see the API reference.

Delete datasets

To delete a dataset, send a DELETE request to the datasets/DATASET_ID endpoint where DATASET_ID is the unique ID of the dataset. For example:

curl -X 'DELETE' 'https://AXIOM_DOMAIN/v2/datasets/test_dataset' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer API_TOKEN'

For more information, see the API reference.