---
title: "Create a dataset"
method: POST
path: "/v1/datasets"
tags: ["Datasets"]
---

# Create a dataset

`POST /v1/datasets`

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.

## Headers

- `Content-Type` string, required

## Request body

- object
  - `title` string — Human-readable name of the dataset. May be empty but not null.
  - `dataSourceId` integer — Unique identifier for the data source.
  - `primaryKeys` string[], nullable — 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`).

## Response `200`

Successful response containing the newly created dataset.

- object
  - `requestId` string — Unique identifier for the request.
  - `status` string — Indicates the status of the request.
  - `id` string, uuid — Unique identifier for the dataset.
  - `title` string, nullable — Human-readable name of the dataset. May be empty but not null.
  - `created` string, date-time — ISO 8601 timestamp when the data source was created.

## Other responses

- `400` — Error response indicating one or more request parameters are invalid.
- `401` — Error response indicating that the API key is missing or invalid.

---

[API](https://skmtc.dev/databox/apis/databox-api.md) · [All operations](https://skmtc.dev/databox/apis/databox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/databox/databox-api/revisions/8e7a3a444e6b/schema)