API Reference

Collections

A Collection is a named collection of node IDs (files from the node tree). Can belong to a Dataset or be standalone.

Collection "front-camera-clips"
  members: [nodeId1, nodeId2, nodeId3]   ← leaf nodes (video, audio, etc.)
  datasetId: "dataset-id"                ← optional parent

POST /namespaces/:slug/projects/:projectSlug/collections

Create a collection.

Property	Value
Auth	JWT
DB roundtrips	3–4

#	Query	Condition
1	`namespace.findUnique({ slug })`	Always
2	`space.findFirst({ nameprojectId, slug })`	Always
3	`dataset.findFirst({ id })`	If `datasetId` provided
4	`collection.create()`	Always

Body

Field	Type	Required	Description
`name`	string	Yes	Collection name (unique within space)
`description`	string	No	Description
`tags`	string[]	No	Tags
`metadata`	object	No	Metadata
`datasetId`	string	No	Parent dataset ID (null = standalone)
`members`	string[]	No	Array of node IDs

Response 201

{
  "id": "collection-id",
  "name": "front-camera-clips",
  "members": ["nodeId1", "nodeId2"],
  "datasetId": "dataset-id",
  "projectId": "space-id",
  "tags": [],
  "createdAt": "2026-04-15T..."
}

Errors

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

GET /namespaces/:slug/projects/:projectSlug/collections

List collections with pagination. Optionally filter by dataset.

Property	Value
Auth	JWT
DB roundtrips	4 (3 effective)

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

Query

Param	Type	Default	Description
`page`	number	1	Page number (1-based)
`pageSize`	number	50	Items per page (max 200)
`datasetId`	string	—	Filter by parent dataset

Response 200

{
  "collections": [
    { "id": "...", "name": "front-camera-clips", "members": ["nodeId1", "nodeId2"], "datasetId": "..." }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1,
  "totalPages": 1
}

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

Get a collection with its members.

Property	Value
Auth	JWT
DB roundtrips	3

Response 200

{
  "id": "collection-id",
  "name": "front-camera-clips",
  "description": null,
  "tags": [],
  "members": ["nodeId1", "nodeId2", "nodeId3"],
  "datasetId": "dataset-id",
  "projectId": "space-id"
}

Errors

Status	Condition
404	Collection not found

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

Update a collection. Can change name, description, tags, members (full replace), or move to a different dataset.

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
`datasetId`	string \| null	Move to dataset or set null for standalone
`members`	string[]	Full replace of members array

Response 200 — updated collection object.

Errors

Status	Condition
404	Collection not found

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

Soft-delete a collection.

Property	Value
Auth	JWT
DB roundtrips	4

Response 200 — { "success": true }

POST /namespaces/:slug/projects/:projectSlug/collections/:name/members

Add node IDs to a collection. Merges with existing members and deduplicates.

Property	Value
Auth	JWT
DB roundtrips	4

Body

Field	Type	Required	Description
`add`	string[]	Yes	Node IDs to add

Response 200

{
  "members": ["nodeId1", "nodeId2", "nodeId3", "nodeId4"],
  "added": 2,
  "total": 4
}

Errors

Status	Condition
400	`add` is empty or not an array
404	Collection not found

DELETE /namespaces/:slug/projects/:projectSlug/collections/:name/members

Remove node IDs from a collection.

Property	Value
Auth	JWT
DB roundtrips	4

Body

Field	Type	Required	Description
`remove`	string[]	Yes	Node IDs to remove

Response 200

{
  "members": ["nodeId1", "nodeId3"],
  "removed": 2,
  "total": 2
}

Errors

Status	Condition
400	`remove` is empty or not an array
404	Collection not found