API Reference

Assets

Assets are files (video, audio, label tracks, text tracks) uploaded via BSS and registered in DreamLake Server.

POST /assets/video

Property	Value
Auth	JWT
DB roundtrips	4 + N

#	Query	Condition
1	`namespace.findUnique({ slug })`	Always
2	`space.upsert({ nameprojectId, slug })`	Always
3	`episode.upsert({ projectId, name })`	If `episodeName` provided
4–N	`node.upsert()` per path segment	If `name` has folder path
N+1	`video.create()`	Always

Body

Field	Type	Required	Description
`namespace`	string	Yes	Namespace slug
`project`	string	Yes	Project slug
`episodeName`	string	No	Episode name (auto-created)
`name`	string	No	Full path (e.g. `/camera/front/run01.mp4`)
`bssVideoId`	string	No	BSS Video ID
`fps`	number	No	Frames per second (default: 30)
`lens`	string	No	`fisheye`, `pinhole`, `eqrec` (default: `pinhole`)
`tags`	string[]	No	Tags
`metadata`	object	No	Arbitrary metadata

Response 201

{
  "id": "video-id",
  "projectId": "space-id",
  "episodeId": "episode-id",
  "name": "/camera/front/run01.mp4",
  "bssVideoId": "bss-video-id"
}

Errors

Status	Condition
400	`namespace` or `space` missing
404	Nameproject not found

POST /assets/audio

Property	Value
Auth	JWT
DB roundtrips	4 + N

Body

Field	Type	Required	Description
`namespace`	string	Yes	Namespace slug
`project`	string	Yes	Project slug
`episodeName`	string	No	Episode name
`name`	string	No	Full path (e.g. `/microphone/front/mic.wav`)
`bssAudioId`	string	No	BSS Audio ID
`sampleRate`	number	No	Sample rate in Hz
`channels`	number	No	Channel count
`tags`	string[]	No	Tags
`metadata`	object	No	Arbitrary metadata

Response 201 — same shape as video (id, projectId, episodeId, name, bssAudioId).

POST /assets/label-track

Property	Value
Auth	JWT
DB roundtrips	4 + N

Body

Field	Type	Required	Description
`namespace`	string	Yes	Namespace slug
`project`	string	Yes	Project slug
`episodeName`	string	No	Episode name
`name`	string	No	Full path (e.g. `/labels/yolo/detections.jsonl`)
`bssLabelId`	string	No	BSS Label ID
`tags`	string[]	No	Tags
`metadata`	object	No	Arbitrary metadata

Response 201 — same shape (id, projectId, episodeId, name, bssLabelId).

POST /assets/text-track

Property	Value
Auth	JWT
DB roundtrips	4 + N

Body

Field	Type	Required	Description
`namespace`	string	Yes	Namespace slug
`project`	string	Yes	Project slug
`episodeName`	string	No	Episode name
`name`	string	No	Full path (e.g. `/subtitles/en/captions.vtt`)
`bssTextTrackId`	string	No	BSS Text Track ID
`format`	string	No	`vtt`, `srt`, or `jsonl`
`language`	string	No	Language code
`tags`	string[]	No	Tags
`metadata`	object	No	Arbitrary metadata

Response 201 — same shape (id, projectId, episodeId, name, bssTextTrackId).

GET /assets/video

List video assets with optional filtering.

Property	Value
Auth	JWT
DB roundtrips	2–3

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

Query

Param	Type	Required	Description
`namespace`	string	Yes	Namespace slug
`project`	string	Yes	Project slug
`episodeId`	string	No	Filter by episode ID
`prefix`	string	No	Filter by name prefix
`glob`	string	No	Glob pattern (e.g. `/camera/front/person*`)

glob takes priority over prefix.

Response 200

[
  {
    "id": "video-id",
    "name": "/camera/front/run01.mp4",
    "bssVideoId": "bss-video-id",
    "fps": 30,
    "lens": "pinhole",
    "createdAt": "2026-04-14T..."
  }
]

GET /assets/video/download

Get a presigned S3 download URL for a video.

Property	Value
Auth	JWT
DB roundtrips	3 + 1 external

#	Query	Condition
1	`namespace.findUnique({ slug })`	Always
2	`space.findFirst({ nameprojectId, slug })`	Always
3	`video.findFirst({ projectId, name })`	Always
4	`fetch BSS /videos/:id/raw`	Always (302 redirect)

Query

Param	Type	Required	Description
`namespace`	string	Yes	Namespace slug
`project`	string	Yes	Project slug
`path`	string	Yes	Full asset path
`episodeId`	string	No	Filter by episode ID

Response 200

{
  "url": "https://s3.amazonaws.com/...presigned...",
  "filename": "run01.mp4"
}

Errors

Status	Condition
400	Missing required params
404	Namespace /project / video not found
404	Video has no BSS record
502	BSS did not return a presigned URL