# 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](/architecture.md#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](/api/project-queries.md).

## 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`](/cli.md#artifacts). 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`](/cli.md#envs). 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`](/libraries.md). 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](/libraries/reference.md).

## LLM Relay

Pass-through to a chat-model API using your DreamLake token instead of a
provider key — the surface behind [LLM Relay](/relay.md). 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) |

## Next steps

    The command-line wrapper over these endpoints.

    The data model and auth flow behind the paths on this page.