Datasets API

Create reusable Datasets, manage draft membership, publish versions, and read exact snapshots.

Outcome: Create reusable Datasets, manage draft membership, publish versions, and read exact snapshots.

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

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

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

Read exact membership

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

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.

Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation.

---

Explore related Unitlab capabilities: training-data curation workflows