# Create a dataset

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.

Endpoint: POST /v1/datasets
Version: v1
Security: x-api-key

## Header parameters:

  - `Content-Type` (string, required)
    Must be set to application/json

## Request fields (application/json):

  - `title` (string)
    Human-readable name of the dataset. May be empty but not null.
    Example: "Transactions"

  - `dataSourceId` (integer)
    Unique identifier for the data source.
    Example: 4754489

  - `primaryKeys` (array,null)
    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"]

## Response 200 fields (application/json):

  - `requestId` (string)
    Unique identifier for the request.
    Example: "b0eac937-c25c-47a5-bb7e-552f6b860458"

  - `status` (string)
    Indicates the status of the request.
    Example: "success"

  - `id` (string)
    Unique identifier for the dataset.
    Example: "4e1219d8-7fa8-44b7-96c6-a8f2a9cfb0bf"

  - `title` (string,null)
    Human-readable name of the dataset. May be empty but not null.
    Example: "Transactions"

  - `created` (string)
    ISO 8601 timestamp when the data source was created.
    Example: "2025-10-01T12:00:00.000000Z"

## Response 400 fields (application/json):

  - `requestId` (string)
    Unique identifier for the request.
    Example: "b0eac937-c25c-47a5-bb7e-552f6b860458"

  - `status` (string)
    Indicates the status of the request.
    Example: "error"

  - `errors` (array)

  - `errors.code` (string,null)
    A machine-readable error code that identifies the type of error.
    Example: "invalid_input"

  - `errors.message` (string)
    A human-readable message explaining the error.
    Example: "The provided parameter is invalid."

  - `errors.field` (string)
    The name of the request field associated with the error, if applicable.
    Example: "datasetId"

  - `errors.type` (string)
    The category or context of the error, such as validation or permission.
    Example: "validation"

## Response 401 fields (application/json):

  - `requestId` (string)
    Unique identifier for the request.
    Example: "b0eac937-c25c-47a5-bb7e-552f6b860458"

  - `status` (string)
    Indicates the status of the request.
    Example: "error"

  - `errors` (array)

  - `errors.code` (string,null)
    A machine-readable error code that identifies the type of error.
    Example: "invalid_input"

  - `errors.message` (string)
    A human-readable message explaining the error.
    Example: "The provided parameter is invalid."

  - `errors.field` (string)
    The name of the request field associated with the error, if applicable.
    Example: "datasetId"

  - `errors.type` (string)
    The category or context of the error, such as validation or permission.
    Example: "validation"