> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/api-sdk-cli/apis/datasets-api.md).

# Datasets API

{% hint style="info" %}
**Outcome:** Create reusable Datasets, manage draft membership, publish versions, and read exact snapshots.
{% endhint %}

### Endpoints

| Method | Endpoint                                   | Purpose                                     |
| ------ | ------------------------------------------ | ------------------------------------------- |
| GET    | `/api/sdk/datasets/`                       | List Datasets                               |
| POST   | `/api/sdk/datasets/`                       | Create from optional folders or Assets      |
| GET    | `/api/sdk/datasets/{dataset_id}/`          | Retrieve metadata                           |
| POST   | `/api/sdk/datasets/{dataset_id}/sources/`  | Add sources to the working draft            |
| GET    | `/api/sdk/datasets/{dataset_id}/items/`    | List draft; add `?version=N` for a snapshot |
| GET    | `/api/sdk/datasets/{dataset_id}/versions/` | List versions and draft-change summary      |
| POST   | `/api/sdk/datasets/{dataset_id}/versions/` | Publish an immutable version                |

### Create and publish

```bash
curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/datasets/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Training set","description":"Approved July cohort","folder_ids":["FOLDER_ID"],"asset_ids":[]}'

curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/datasets/DATASET_ID/versions/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"version_title":"July baseline","description":"Initial reviewed cohort"}'
```

![New Dataset source-selection dialog](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2F878wtKnyECkRNbmyCKhY%2Fdataset-create-modal.png?alt=media\&token=d09720b0-5aa9-4019-a940-d702f6a40e88)

*The API creates the same reusable named membership assembled from reviewed folders and Assets in Data Space.*

### Read exact membership

```bash
curl --fail-with-body --silent --show-error \
  "$UNITLAB_API_URL/api/sdk/datasets/DATASET_ID/items/?version=3" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY"
```

Follow `next` until empty. A draft can change; a numbered version is the reproducible snapshot to attach to a Project.

![Dataset history and versions](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FVlkSuopZNbC9JUP9uVx1%2Fdataset-history.png?alt=media\&token=27ae53b7-17d1-45dc-a93b-200509328987)

*History exposes publisher, time, item count, membership delta, and the immutable version number used by automation.*

### Request operating contract

| Concern           | Required behavior                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| Execution surface | TLS-verified client using the reviewed current public `/api/sdk/...` route contract.                  |
| Identity          | Least-privilege workspace service identity; secrets remain outside code and logs.                     |
| Request boundary  | URL-encoded stable IDs, explicit deadlines, structured errors, and complete pagination.               |
| Success evidence  | Response identifiers, read-after-write verification, and separate processing status for Batch Queues. |

{% hint style="warning" %}
Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation.
{% endhint %}