API Reference

Datasets

A Dataset is a named container that groups related Collections together. Space-scoped.

Space
├── Dataset "training-v2"
│   ├── Collection "front-camera-clips"
│   └── Collection "good-detections"
└── Dataset "eval-set"
    └── Collection "edge-cases"

POST /namespaces/:slug/projects/:projectSlug/datasets

Create a dataset.

Property	Value
Auth	JWT
DB roundtrips	3

#	Query	Condition
1	`namespace.findUnique({ slug })`	Always
2	`space.findFirst({ nameprojectId, slug })`	Always
3	`dataset.create()`	Always

Body

Field	Type	Required	Description
`name`	string	Yes	Dataset name (unique within space)
`description`	string	No	Description
`tags`	string[]	No	Tags
`metadata`	object	No	Arbitrary metadata

Response 201

{
  "id": "dataset-id",
  "name": "training-v2",
  "description": "Q1 training data",
  "tags": [],
  "projectId": "space-id",
  "metadata": null,
  "createdAt": "2026-04-15T...",
  "updatedAt": "2026-04-15T..."
}

Errors

Status	Condition
400	`name` missing
404	Namespace / project not found
409	Dataset name already exists in this project

GET /namespaces/:slug/projects/:projectSlug/datasets

List datasets with pagination.

Property	Value
Auth	JWT
DB roundtrips	4 (3 effective)

#	Query	Condition	Parallel
1	`namespace.findUnique({ slug })`	Always	—
2	`space.findFirst({ nameprojectId, slug })`	Always	—
3	`dataset.findMany({ projectId })`	Always	✓
4	`dataset.count({ projectId })`	Always	✓

Query

Param	Type	Default	Description
`page`	number	1	Page number (1-based)
`pageSize`	number	50	Items per page (max 200)

Response 200

{
  "datasets": [
    { "id": "...", "name": "training-v2", "description": "Q1 training data", "tags": [] }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1,
  "totalPages": 1
}

GET /namespaces/:slug/projects/:projectSlug/datasets/:name

Get a dataset with all its collections.

Property	Value
Auth	JWT
DB roundtrips	4

#	Query	Condition
1	`namespace.findUnique({ slug })`	Always
2	`space.findFirst({ nameprojectId, slug })`	Always
3	`dataset.findFirst({ projectId, name })`	Always
4	`collection.findMany({ datasetId })`	Always

Response 200

{
  "id": "dataset-id",
  "name": "training-v2",
  "description": "Q1 training data",
  "tags": [],
  "collections": [
    { "id": "...", "name": "front-camera-clips", "members": ["nodeId1", "nodeId2"] },
    { "id": "...", "name": "good-detections", "members": ["nodeId3"] }
  ]
}

Errors

Status	Condition
404	Namespace /project / dataset not found

PATCH /namespaces/:slug/projects/:projectSlug/datasets/:name

Update a dataset. Only provided fields are updated.

Property	Value
Auth	JWT
DB roundtrips	4

Body (all optional)

Field	Type	Description
`name`	string	New name
`description`	string	Description
`tags`	string[]	Tags
`metadata`	object	Metadata

Response 200 — updated dataset object.

Errors

Status	Condition
404	Dataset not found

DELETE /namespaces/:slug/projects/:projectSlug/datasets/:name

Soft-delete a dataset. Collections inside are NOT deleted — they become standalone.

Property	Value
Auth	JWT
DB roundtrips	4

Response 200 — { "success": true }

Errors

Status	Condition
404	Dataset not found