API Reference
The REST surface behind the CLI and dashboard. Endpoints are grouped by resource; every path below is relative to your server's base URL.
Base URL: https://api.dreamlake.ai in production, http://localhost:3001
in local dev. All endpoints require Authorization: Bearer <token> unless
noted — see Architecture § Auth for how tokens are
issued.
Auth
| Method | Path | Description |
|---|---|---|
| POST | /auth/exchange | Exchange vuer-auth token for dreamlake JWT (no auth required) |
| GET | /auth/me | Current user profile |
| PATCH | /auth/me | Update profile |
Namespaces & Projects
| Method | Path | Description |
|---|---|---|
| GET | /auth/namespaces | List public namespaces (no auth) |
| GET | /namespaces/:slug | Namespace overview with asset counts |
| PATCH | /namespaces/:slug | Update namespace (owner only) |
| GET | /namespaces/:slug/projects | List projects |
| POST | /namespaces/:slug/projects | Create project |
| PATCH | /namespaces/:slug/projects/:proj | Update project |
For GraphQL project/Note reads and equivalent REST association and choice views, see Project and Note queries.
Episodes
| Method | Path | Description |
|---|---|---|
| POST | /namespaces/:slug/projects/:proj/episodes | Create/upsert episode |
| GET | /namespaces/:slug/projects/:proj/episodes | List episodes (paginated) |
| PATCH | /namespaces/:slug/projects/:proj/episodes/:name | Update episode |
Nodes (File Tree)
| Method | Path | Description |
|---|---|---|
| POST | /nodes | Create node (auto-creates hierarchy) |
| GET | /nodes | List nodes by namespace/project/kind |
| GET | /nodes/children | List 1-level children |
| GET | /nodes/lookup | Resolve node by materialized path |
| GET | /nodes/:id/descendants | All descendants (recursive) |
| GET | /nodes/:id/contents | Episodes + files (paginated) |
| GET | /nodes/:id/download | Presigned S3 download URL |
| PATCH | /nodes/:id | Update node (name, move, tags) |
| DELETE | /nodes/:id | Hard-delete node + descendants |
Files
| Method | Path | Description |
|---|---|---|
| POST | /episodes/:id/files | Upload file (multipart) |
| GET | /episodes/:id/files | List files |
| GET | /episodes/:id/files/:fid/download | Download file |
| DELETE | /episodes/:id/files/:fid | Delete file |
Tracks & Logs
| Method | Path | Description |
|---|---|---|
| POST | /episodes/:id/tracks/:name/append | Append data point |
| POST | /episodes/:id/tracks/:name/append-batch | Append batch |
| GET | /episodes/:id/tracks/:name/data | Read track data |
| GET | /episodes/:id/tracks | List tracks |
| POST | /episodes/:id/logs | Create log entries |
| GET | /episodes/:id/logs | Query logs (level, time, search) |
Parameters
| Method | Path | Description |
|---|---|---|
| POST | /episodes/:id/parameters | Set/merge parameters |
| GET | /episodes/:id/parameters | Get parameters |
| DELETE | /episodes/:id/parameters | Soft-delete |
Bindrs & Datasets
| Method | Path | Description |
|---|---|---|
| POST | …/bindrs | Create bindr |
| GET | …/bindrs | List bindrs |
| GET | …/bindrs/:name | Get bindr |
| PATCH | …/bindrs/:name | Update bindr |
| DELETE | …/bindrs/:name | Soft-delete |
| POST | …/bindrs/:name/members | Add members |
| DELETE | …/bindrs/:name/members | Remove members |
| POST | …/datasets | Create dataset |
| GET | …/datasets | List datasets |
| GET | …/datasets/:name | Get dataset with bindrs |
| PATCH | …/datasets/:name | Update dataset |
| DELETE | …/datasets/:name | Soft-delete |
All bindr/dataset paths are under /namespaces/:slug/projects/:proj/.
Artifacts
Renderable, versioned documents with per-artifact visibility — the surface
behind dreamlake artifact. Public/list/read routes apply
per-artifact policy themselves (member / public / valid share).
| Method | Path | Description |
|---|---|---|
| GET | /namespaces/:slug/artifacts | Catalog list (members: all; others: public only). ?deleted=true lists the Trash (members) |
| GET | /namespaces/:slug/artifacts/:id | One catalog row + viewerCanManage (?share= for share links) |
| POST | /namespaces/:slug/artifacts/upload-credentials | Mint scoped STS creds for a push (member) |
| POST | /namespaces/:slug/artifacts/:id | Upsert catalog entry — metadata / visibility / share token (member) |
| POST | /namespaces/:slug/artifacts/read-token | Mint a short-lived per-artifact read token |
| GET | /namespaces/:slug/artifacts/read/:token/* | Read-proxy: stream artifact objects (Range-aware) |
| DELETE | /namespaces/:slug/artifacts/:id | Soft delete → Trash (member) |
| POST | /namespaces/:slug/artifacts/:id/restore | Restore from Trash (member) |
| DELETE | /namespaces/:slug/artifacts/:id/purge | Permanent purge — storage + catalog, irreversible (member) |
| GET | /me/artifacts | Signed-in user's artifacts: yours + shared-with-you, tagged by group |
Envs
Versioned simulation environments (MJCF + assets) — the surface behind
dreamlake env. Env file bytes never transit the API: uploads go
straight to storage with brokered STS credentials, and reads hand back one
presigned URL per file. Public routes apply per-env policy themselves; a
hidden env answers 404, never 403.
| Method | Path | Description |
|---|---|---|
| GET | /namespaces/:slug/envs | Catalog list (members: all; others: public only). ?deleted=true lists the Trash (members) |
| GET | /namespaces/:slug/envs/:name | One catalog row + viewerCanManage + thumbVersion |
| GET | /namespaces/:slug/envs/:name/versions | All pushed versions, newest first |
| GET | /namespaces/:slug/envs/:name/versions/:version | One version's manifest — entry + per-file {path, size, hash, url} with presigned GETs (:version int or latest) |
| POST | /namespaces/:slug/envs/upload-credentials | Mint STS creds scoped to envs/<ns>/<name>/ for a push (member) |
| POST | /namespaces/:slug/envs/:name | Register a pushed version (create-or-revive, latestVersion = max), or patch title/description/envType/visibility (member) |
| POST | /namespaces/:slug/envs/:name/thumbnail | Store the browser-captured PNG thumbnail, ≤ 512 KB (member) |
| DELETE | /namespaces/:slug/envs/:name | Soft delete → Trash (member) |
| POST | /namespaces/:slug/envs/:name/restore | Restore from Trash (member) |
| DELETE | /namespaces/:slug/envs/:name/purge | Permanent purge — whole storage prefix + catalog, irreversible (member) |
Libraries
Asset collections stored verbatim under one storage prefix, searchable per
asset — the surface behind dreamlake library. Payload bytes
never transit the API: uploads and downloads run on presigned batches straight
to storage. Public routes apply per-library policy themselves (member /
public visibility / valid ?share=<token>); a hidden library answers
404, never 403.
| Method | Path | Description |
|---|---|---|
| GET | /namespaces/:slug/libraries | Catalog list (members: all; others: public only). ?deleted=true lists the Trash (members) |
| GET | /namespaces/:slug/libraries/:name | One catalog row (LibraryDetail) + viewerCanManage |
| GET | /namespaces/:slug/libraries/:name/manifest | The full parsed wire manifest (dreamlake.assets/v1), served verbatim |
| GET | /namespaces/:slug/libraries/:name/assets/:assetId | One asset with presigned per-file URLs — the preview payload (?ttlSeconds) |
| POST | /namespaces/:slug/libraries/:name/files-presign | Presigned GETs for manifest paths, ≤ 1,000 per batch — the pull payload (ttlSeconds) |
| GET | /namespaces/:slug/libraries/:name/search | Search inside one library (q, category, kind, license, tag, limit ≤ 200, offset) |
| GET | /libraries | Visible libraries across namespaces, newest first (limit ≤ 500) |
| GET | /library-search | Cross-library search over libraries=ns/a,ns/b (≤ 50); inaccessible targets land in skipped[] |
| POST | /namespaces/:slug/libraries/:name/upload-authorizations | Presigned upload batch for a push (member) |
| POST | /namespaces/:slug/libraries/:name/register | Validate the uploaded manifest, bump revision (CAS — stale expectedRevision → 409), reconcile storage (member) |
| POST | /namespaces/:slug/libraries/:name | Patch visibility / share token — content metadata is manifest-derived (member) |
| DELETE | /namespaces/:slug/libraries/:name | Soft delete → Trash (member) |
| POST | /namespaces/:slug/libraries/:name/restore | Restore from Trash (member) |
| DELETE | /namespaces/:slug/libraries/:name/purge | Permanent purge — storage prefix + catalog, irreversible (member) |
Full request/response schemas, the manifest contract, and agent read patterns live in Libraries Reference.
LLM Relay
Pass-through to a chat-model API using your DreamLake token instead of a
provider key — the surface behind LLM Relay. The path under
/relay/:provider/ is forwarded to the provider verbatim, so its whole API is
reachable. Authenticate with Authorization: Bearer or x-api-key.
| Method | Path | Description |
|---|---|---|
| GET | /relay/providers | Which providers this deployment can relay to, and the base URL for each |
| POST | /relay/:provider/v1/messages | Relay a chat completion (stream: true streams SSE straight back) |
| POST | /relay/:provider/v1/messages/count_tokens | Relay a token count |
| GET | /relay/:provider/v1/models | Relay the provider's live model list |
Search
| Method | Path | Description |
|---|---|---|
| POST | /projects/:id/search | Project-wide vector search |
| POST | /projects/:id/episodes/:eid/search | Episode-scoped search |
| POST | …/assets/search | Semantic search (CLIP text/image) |
Health
| Method | Path | Description |
|---|---|---|
| GET | /health | Server status (no auth) |