# Databox API

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.


Version: v1

## Servers

Production server
```
https://api.databox.com
```

## Security

### x-api-key

API key for authentication

Type: apiKey
In: header
Name: x-api-key

## Download OpenAPI description

[Databox API](https://developers.databox.com/_bundle/api/@v1/api.databox.com.yaml)

## Accounts

Access account details, configuration, and associated resources.

### List accounts

 - [GET /v1/accounts](https://developers.databox.com/api/api.databox.com/accounts/accounts_getaccounts.md): Retrieves all accounts accessible to the user associated with the API key.

### List data sources

 - [GET /v1/accounts/{accountId}/data-sources](https://developers.databox.com/api/api.databox.com/accounts/accounts_getdatasources.md): Retrieves the list of ingestible data sources available for the specified account.  
Only data sources that can accept ingested data and be created via the API are included.

### List time zones

 - [GET /v1/accounts/timezones](https://developers.databox.com/api/api.databox.com/accounts/accounts_gettimezones.md): Retrieves the list of all timezones supported by Databox, including their UTC offsets and IANA identifiers.

## Auth

Authentication and API key validation operations.

### Validate an API key

 - [GET /v1/auth/validate-key](https://developers.databox.com/api/api.databox.com/auth/auth_validateapikey.md): Validates the API key supplied in the x-api-key header.

Use this endpoint as a setup/health check. Integration partners can call it to confirm
a customer's key before enabling data ingestion or completing account linking.
- 200 OK: Key is valid.
- 401 Unauthorized: Key is missing or invalid (standard error envelope).

## Data Sources

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

### Create a data source

 - [POST /v1/data-sources](https://developers.databox.com/api/api.databox.com/data-sources/datasources_postcreate.md): Creates an ingestion data source (a container for one or more datasets).

If accountId is provided, the data source is created in that account;
otherwise, it is created in the account associated with the API key.

Requires a valid x-api-key with permission to create data sources in the target account.

### Delete a data source

 - [DELETE /v1/data-sources/{dataSourceId}](https://developers.databox.com/api/api.databox.com/data-sources/datasources_delete.md): Permanently deletes the specified ingestion data source (dataSourceId).

Deleting a data source also deletes all datasets it contains (and their data). This action is irreversible.

Requires a valid x-api-key with permission to manage data sources in the target account.

### List datasets

 - [GET /v1/data-sources/{dataSourceId}/datasets](https://developers.databox.com/api/api.databox.com/data-sources/datasources_getdatasets.md): Retrieves all datasets that belong to the specified data source (dataSourceId).

## Datasets

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

### Create a dataset

 - [POST /v1/datasets](https://developers.databox.com/api/api.databox.com/datasets/datasets_postcreate.md): 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.

### Delete a dataset

 - [DELETE /v1/datasets/{datasetId}](https://developers.databox.com/api/api.databox.com/datasets/datasets_delete.md): Deletes the specified dataset. This action permanently removes all associated data and cannot be reversed.

### Purge a dataset

 - [POST /v1/datasets/{datasetId}/purge](https://developers.databox.com/api/api.databox.com/datasets/datasets_postpurge.md): 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.

### Create an ingestion

 - [POST /v1/datasets/{datasetId}/data](https://developers.databox.com/api/api.databox.com/datasets/datasets_postcreateingestion.md): 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.

### List ingestions

 - [GET /v1/datasets/{datasetId}/ingestions](https://developers.databox.com/api/api.databox.com/datasets/datasets_getlistingestions.md): 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.

### Retrieve an ingestion

 - [GET /v1/datasets/{datasetId}/ingestions/{ingestionId}](https://developers.databox.com/api/api.databox.com/datasets/datasets_getingestion.md): Retrieves detailed information for an ingestion event, allowing you to check processing progress and outcomes.