Skip to content
/
Retrieve an ingestion

Databox API (v1)

The Databox API allows you to integrate Databox with external systems, automate data ingestion, and extend platform functionality. It follows REST conventions with resource-oriented URLs, JSON request/response bodies, and standard HTTP methods/status codes.

Download OpenAPI description
api.databox.com.json
api.databox.com.yaml
Languages
Servers
Production server

https://api.databox.com/

Accounts

Access account details, configuration, and associated resources.

Operations

Auth

Authentication and API key validation operations.

Operations

Data Sources

Create and delete data sources; list datasets for a data source.

Operations

Datasets

Create, ingest into, purge, and delete datasets; list and inspect ingestions.

Operations

Create a dataset

Request

Creates a new dataset within the specified data source. A dataset acts as a container for ingested data and can later be populated with rows. Once created, the dataset can be used for reporting, visualizations, and transformations within the platform.

Notes:

  • Requires a valid x-api-key with permission to manage datasets in the target account.
  • Each dataset must belong to an existing data source; it cannot exist independently.
  • The dataset is created empty; data is added afterward through ingestion events.
Security
x-api-key
Headers
Content-Typestringrequired

Must be set to application/json

Bodyapplication/jsonrequired
titlestring(title.dataset)

Human-readable name of the dataset. May be empty but not null.

Example: "Transactions"
dataSourceIdinteger(int64)(dataSourceId)

Unique identifier for the data source.

Example: 4754489
primaryKeysArray of strings or null or null(primaryKeys)

Array of column names that uniquely identify rows in the dataset.
if the dataset has no unique columns or identifiers, this field can be omitted (null).

Example: ["invoice_id"]
curl -i -X POST \
  https://api.databox.com/v1/datasets \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "title": "Transactions",
    "dataSourceId": 4754489,
    "primaryKeys": [
      "invoice_id"
    ]
  }'

Responses

Successful response containing the newly created dataset.

Bodyapplication/json
requestIdstring

Unique identifier for the request.

Example: "b0eac937-c25c-47a5-bb7e-552f6b860458"
statusstring

Indicates the status of the request.

Example: "success"
idstring(uuid)

Unique identifier for the dataset.

Example: "4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf"
titlestring or null

Human-readable name of the dataset. May be empty but not null.

Example: "Transactions"
createdstring(date-time)

ISO 8601 timestamp when the data source was created.

Example: "2025-10-01T12:00:00.000000Z"
Response
application/json
{
  "requestId": "b0eac937-c25c-47a5-bb7e-552f6b860458",
  "status": "success",
  "id": "4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf",
  "title": "Transactions",
  "created": "2025-10-01T12:00:00.000000Z"
}

Delete a dataset

Request

Deletes the specified dataset. This action permanently removes all associated data and cannot be reversed.

Security
x-api-key
Path
datasetIdstring(uuid)(datasetId)required

Unique identifier for the dataset.

Example: 4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf
curl -i -X DELETE \
  https://api.databox.com/v1/datasets/4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response indicating that the data source and all contained datasets were permanently deleted.

Bodyapplication/json
requestIdstring

Unique identifier for the request.

Example: "b0eac937-c25c-47a5-bb7e-552f6b860458"
statusstring

Indicates the status of the request.

Example: "success"
messagestring

Human-readable message describing the outcome of the request (for display/logging; not intended for programmatic parsing).

Example: "Resource deleted successfully"
Response
application/json
{
  "requestId": "b0eac937-c25c-47a5-bb7e-552f6b860458",
  "status": "success",
  "message": "Dataset deleted successfully"
}

Purge a dataset

Request

Purges the specified dataset by removing all rows of data it contains. The dataset itself remains intact and can continue to receive new ingestions.

This operation is irreversible — once purged, the deleted data cannot be restored.

Security
x-api-key
Path
datasetIdstring(uuid)(datasetId)required

Unique identifier for the dataset.

Example: 4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf
Headers
Content-Typestringrequired

Must be set to application/json

curl -i -X POST \
  https://api.databox.com/v1/datasets/4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf/purge \
  -H 'Content-Type: string' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response indicating that the dataset has been purged.

Bodyapplication/json
requestIdstring

Unique identifier for the request.

Example: "b0eac937-c25c-47a5-bb7e-552f6b860458"
statusstring

Indicates the status of the request.

Example: "success"
messagestring

Human-readable message describing the outcome of the request (for display/logging; not intended for programmatic parsing).

Example: "Resource deleted successfully"
Response
application/json
{
  "requestId": "b0eac937-c25c-47a5-bb7e-552f6b860458",
  "status": "success",
  "message": "Dataset purged successfully"
}

Create an ingestion

Request

Adds a batch of data records to the specified dataset through an ingestion event.

You can include up to 100 records per ingestion event.

The returned ingestionId values can be used with the corresponding ingestion details endpoint to retrieve more information the ingestion event.

Security
x-api-key
Path
datasetIdstring(uuid)(datasetId)required

Unique identifier for the dataset.

Example: 4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf
Headers
Content-Typestringrequired

Must be set to application/json

Bodyapplication/jsonrequired
recordsArray of objects(records.item)required

Aray of arbitrary key-value pairs representing a single event, item, or row.

records[].​property name*anyadditional property
curl -i -X POST \
  https://api.databox.com/v1/datasets/4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf/data \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "records": [
      {
        "transactionId": "9826",
        "occurredAt": "2025-10-01T12:00:00.000000Z",
        "amount": 42.5,
        "tags": [
          "promo",
          "returning"
        ]
      }
    ]
  }'

Responses

Successful response containing confirmation that the ingestion request was accepted.

Bodyapplication/json
requestIdstring

Unique identifier for the request.

Example: "b0eac937-c25c-47a5-bb7e-552f6b860458"
statusstring

Indicates the status of the request.

Example: "success"
ingestionIdstring(uuid)

Unique identifier for the ingestion event.

Example: "8bfba187-84f4-41e2-9dd3-bee4bb884205"
messagestring(date-time)

Human-readable message describing the outcome of the request (for display/logging; not intended for programmatic parsing).

Example: "Data ingestion request accepted"
Response
application/json
{
  "requestId": "b0eac937-c25c-47a5-bb7e-552f6b860458",
  "status": "success",
  "ingestionId": "8bfba187-84f4-41e2-9dd3-bee4bb884205",
  "message": "Data ingestion request accepted"
}

List ingestions

Request

Retrieves a list of ingestions events that have been created for the specified dataset.

The returned ingestionId values can be used with the corresponding ingestion details endpoint to retrieve more information about a specific ingestion event.

Security
x-api-key
Path
datasetIdstring(uuid)(datasetId)required

Unique identifier for the dataset.

Example: 4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf
curl -i -X GET \
  https://api.databox.com/v1/datasets/4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf/ingestions \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response containing a list of ingestion events for the specified dataset.

Bodyapplication/json
requestIdstring

Unique identifier for the request.

Example: "b0eac937-c25c-47a5-bb7e-552f6b860458"
statusstring

Indicates the status of the request.

Example: "success"
ingestionsArray of objects(ingestion.list)

List of ingestion events.

Response
application/json
{
  "requestId": "b0eac937-c25c-47a5-bb7e-552f6b860458",
  "status": "success",
  "ingestions": [
    { … }
  ]
}

Retrieve an ingestion

Request

Retrieves detailed information for an ingestion event, allowing you to check processing progress and outcomes.

Security
x-api-key
Path
datasetIdstring(uuid)(datasetId)required

Unique identifier for the dataset.

Example: 4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf
ingestionIdstring(uuid)(ingestionId)required

Unique identifier for the ingestion event.

Example: 8bfba187-84f4-41e2-9dd3-bee4bb884205
curl -i -X GET \
  https://api.databox.com/v1/datasets/4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf/ingestions/8bfba187-84f4-41e2-9dd3-bee4bb884205 \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful response containing detailed information about the requested ingestion event.

Bodyapplication/json
requestIdstring

Unique identifier for the request.

Example: "b0eac937-c25c-47a5-bb7e-552f6b860458"
statusstring

Indicates the status of the request.

Example: "success"
ingestionIdstring(uuid)(ingestionId)

Unique identifier for the ingestion event.

Example: "8bfba187-84f4-41e2-9dd3-bee4bb884205"
timestampstring
Example: "2025-10-01T12:00:00.000000Z"
metricsobject(metrics)

Metrics summarizing dataset characteristics and the outcome of the ingestion event

Response
application/json
{
  "requestId": "b0eac937-c25c-47a5-bb7e-552f6b860458",
  "status": "success",
  "ingestionId": "8bfba187-84f4-41e2-9dd3-bee4bb884205",
  "timestamp": "2025-10-01T12:00:00.000000Z",
  "metrics": {
    "datasetMetrics": { … },
    "ingestionMetrics": { … }
  }
}