DreamLake

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

MethodPathDescription
POST/auth/exchangeExchange vuer-auth token for dreamlake JWT (no auth required)
GET/auth/meCurrent user profile
PATCH/auth/meUpdate profile

Skills registry

MethodPathDescription
GET/skillsAuthenticated catalog with the server's pinned tag/commit.
GET/skills/:skillManifest, SKILL.md body and file index from that bundle.
GET/skills/:skill/files/*Pinned text file, with content-hash ETag and version headers.

The registry is read-only. Public release, CLI embedded and server pins are separate; verify the served version and bytes. See authenticated skills API.

Namespaces & Projects

MethodPathDescription
GET/auth/namespacesList public namespaces (no auth)
GET/namespaces/:slugNamespace overview with asset counts
PATCH/namespaces/:slugUpdate namespace (owner only)
GET/namespaces/:slug/projectsList projects
POST/namespaces/:slug/projectsCreate project; capability-gated accessMode: "restricted" with private visibility creates it restricted atomically
PATCH/namespaces/:slug/projects/:projUpdate project, including its slug
DELETE/namespaces/:slug/projects/:projSoft-delete project: unmount everything filed in it, revoke its grants, release its slug; resources are kept (project admin)
GET/namespaces/:slug/projects/:proj/accessRead Workspace/Restricted policy and caller authority
PATCH/namespaces/:slug/projects/:proj/accessSet policy and optional explicit visibility atomically (project admin)
GET/namespaces/:slug/projects/:proj/audienceComplete bounded effective human audience and access sources (project admin)
GET/namespaces/:slug/projects/:proj/grantsList direct grants and baseline metadata (project admin); not the whole audience
POST/namespaces/:slug/projects/:proj/grantsAdd or update user/team access (project admin)
DELETE/namespaces/:slug/projects/:proj/grants/:grantIdRemove a grant from this project (project admin)

For GraphQL project/Note reads and equivalent REST association and choice views, see Project and Memo queries.

A project slug is a single path segment: creating a project (here or with POST /nodes kind=project), or changing its slug through this PATCH or PATCH /nodes/:id, answers 400 for an empty slug, one containing , or /, or exactly . or .., which URLs normalize away. Other dots are allowed, as in v1.2. Renaming rewrites only the leading project segment of every descendant path, so a folder that shares the old slug keeps its name.

Project field limits

Project rename supports name, slug, slugMode (auto or custom), expectedProjectId, and expectedSlugRevision. New projects without an explicit slug follow their name; explicit custom slugs and legacy preferences persist. Historical browser addresses remain reserved and resolve with current access. See Project names and addresses for input semantics, stable-ID updates, collision handling and old-link resolution.

All four project writers — POST and PATCH /namespaces/:slug/projects…, POST /nodes kind=project and PATCH /nodes/:id on a project — apply the same limits to the values they would store. Lengths count Unicode code points (𝄞, an emoji and 机 are one each), with no normalization.

FieldLimit
name (metadata.displayName)A single-line string, 1–100 code points after trimming; stored trimmed
slug1–100 code points, plus the slug rules above. A slug generated from the name always fits: only the part derived from the name is shortened, never the hash suffix. An explicit longer slug is refused, never cut
description (metadata.description)null or a string of at most 500 code points, counted whole: spaces and line breaks are kept and count
tagsEach 1–50 code points after trimming. Stored trimmed with exact duplicates removed (" a" and "a" are one tag; "A" is another), at most 20
metadataAt most 16384 bytes as compact UTF-8 JSON and nested at most 5 deep, after the merge. The object is depth 1; each nested object or array, even empty, adds one

name and description are stored in metadata, count toward its size, and obey the same rules when sent as metadata.displayName or metadata.description. When both forms are sent, metadata still wins. A PATCH checks the merged result as read in its own transaction, so patches that each fit cannot add up past the limit.

A value outside its limit is refused with 400 and nothing changes. The body names the field and its measurement without repeating the content: { "error": "description is 501 code points; the limit is 500", "code": "project_field_invalid", "details": { "field": "description", "actual": 501, "limit": 500, "unit": "code points" } }. details.field is displayName, slug, description, tags (with index for one tag), metadata, or metadata.displayName / metadata.description.

POST /nodes kind=project now stores the tags it is sent on a new project. Posting a slug that already names a project still answers with that project and writes and checks nothing.

Existing values are not migrated, trimmed or checked until a write changes them. An edit that leaves a field alone — only visibility, tags or the slug, or resending the stored value — succeeds and keeps it. A new value must fit, and once a request changes metadata content, including name or description, the whole merged metadata must fit. A project whose other metadata is already over a limit therefore cannot change its name or description until the same request brings the merged object within it, for example by setting a large key to null: the merge never removes keys.

Project delete is a soft delete, and the only project delete there is: DELETE /nodes/:id on a project node runs the same delete (the dashboard and CLI use that form, by project ID), and answers deleted: 1 with the same fields. Only Project ADMIN can delete — which includes the personal namespace owner and organization OWNERs; READ and WRITE get 403.

The delete marks the project and its Bindrs deleted, removes their Bindr memberships, unmounts every Memo, artifact, workflow, annotation and env filed in the project, and removes every user, team and service-account grant on it. The resources themselves, their filings in other projects and their own shares are kept. The project's folders, files, episodes, Datasets and stored objects are kept too, with their IDs, but are no longer reachable; nothing is queued for cleanup. Tasks, task events and finished runs keep the project's ID. A Note that was filed there stays renamable and deletable like any other. There is no restore endpoint.

The current slug is released unless it is also a reserved historical address from a previous rename. An unreserved slug can be used by a new project, which gets a new ID. An old URL that names only the slug opens the new project; the old project's ID, files, folders, mounts and runs never resolve through it. The deleted project is kept as a tombstone under its original ID, recording its namespace, original slug and name, when it was deleted and by whom. A project deleted before slug release still holds its slug, so creating that slug answers 409 until an operator releases it.

Because a slug can pass to a new project, an edit made from a project the caller already loaded should name it: send its ID as expectedProjectId in the PATCH /namespaces/:slug/projects/:proj body. The usual project:update check on the slug runs first and answers as before: 404 when no project holds the slug, 403 or 404 for a caller without access. Then, in the same transaction as the write, the update is refused with 409 and changes nothing unless the project being written is that live project — for example when its slug now belongs to a newer project, or it is deleted while the request runs. Any supplied value counts, so an empty string is refused too. The field is a precondition only and is never stored. Without the field the request updates whichever project holds the slug, as before; callers that address a project by slug alone, such as scripts, keep working unchanged. A server released before this field ignores it and applies the edit to the current holder of the slug, so a client that depends on the binding needs a server that has it.

The delete is refused with 409 and changes nothing while computation bound to the project is still active: a managed run submitted to the project that is queued, running or cancel_requested, or an embedding job that is pending, queued or running. The body is { error, code: "PROJECT_COMPUTE_ACTIVE", computations: [{ kind, id, status, cancelRequested? }] }; finish or cancel them and retry. Finished runs do not block, and neither does a workflow merely filed in the project, which runs in its namespace. Once deleted, the project admits no new run, mount, grant or write. A concurrent change can also answer 409 (OPERATION_CONFLICT); retry it.

The same delete removes the project's Source bindings and the Bindr references to them. The Sources stay, and can still be managed and deleted. If the project's reference graph is inconsistent, the delete answers 500 and changes nothing.

Deleting a workflow, artifact, annotation or scene works the other way round on a server that includes the issue #1343 fix (not yet in a released server; older servers leave the placements behind). The delete removes the resource from every project it is filed in, together with the Bindr memberships on those placements, in the same transaction as the delete. This holds for soft deletes and for permanent purges. Placements in other projects, including external mounts, are removed with it. Unmounting changes no sharing on its own: other resources' placements, project grants and share links are unaffected, and a soft delete keeps the resource's external mount grants. The deleted resource's existing deletion policy still applies; for example, a soft delete revokes an artifact or scene share link, and a purge revokes its external mount grants and an artifact purge removes its recorded share access. Restoring an artifact or scene, or creating an annotation again under its old name, brings it back unfiled. Mount it again where you want it. A same-named replacement can take the old position at once. When a purge cannot delete the stored objects, it answers 500 and leaves the resource and its placements as they were.

Project grant management accepts exactly one of granteeId, granteeSlug, or teamId, with role: "READ" | "WRITE" | "ADMIN". Teams must belong to the Project's organization. Use /access for current policy, /grants for direct grants, and /audience for the complete bounded human audience and contributing access paths. Restricted mode removes organization-member READ; private visibility alone does not. Namespace owners retain ADMIN/recovery and independent resource shares remain separate. See Project access management for released client versions, atomic creation, limits and interface coverage.

Episodes

MethodPathDescription
POST/namespaces/:slug/projects/:proj/episodesCreate/upsert episode
GET/namespaces/:slug/projects/:proj/episodesList episodes (paginated)
PATCH/namespaces/:slug/projects/:proj/episodes/:nameUpdate episode

Memos

MethodPathDescription
GET/namespaces/:slug/notesList or search accessible Memos; includeArchived=true includes archived Memos
GET/notes/:noteIdAuthorized direct metadata read, including archivedAt
PATCH/namespaces/:slug/notes/:noteIdChange Memo metadata, or separately archive/unarchive with archived
GET/namespaces/:slug/notes/searchSearch body passages with archive filtering and continuation
GET/me/notes/sharedShared Memos, with optional archived results

Catalog results (GET /namespaces/:slug/notes, including q searches) and GET /me/notes/shared include projects and bindrs summaries. Each Bindr is {id, name, projectId, projectSlug, namespaceSlug}; its namespace identifies the containing project, which can differ from the Memo's owner. Open it at /{namespaceSlug}/bindrs/{id}. Summaries include only live Bindrs on valid Memo filings in projects the caller can read. An empty array reveals nothing about inaccessible associations. These fields enrich the current page without changing catalog search, totals, or pagination; direct Memo metadata reads need not include them.

See Memo and folder archival for the full lifecycle contract, permissions, errors, query defaults and matching client/tool interfaces. The Memos API design separately tracks the wider interface redesign.

Nodes (File Tree)

MethodPathDescription
POST/nodesCreate node (auto-creates hierarchy)
GET/nodesList nodes by namespace/project/kind
GET/nodes/childrenList children or search recursively; includeArchived controls archive filtering
GET/nodes/lookupResolve node by materialized path
GET/nodes/:id/descendantsComplete recursive inventory by default; includeArchived=false selects active descendants
GET/nodes/:id/contentsComplete episode/file inventory by default; includeArchived=false selects active results
GET/nodes/:id/downloadPresigned S3 download URL
PATCH/nodes/:idUpdate node (name, move, tags), or separately archive/unarchive a folder
DELETE/nodes/:idHard-delete node + descendants

Folders have independent archivedAt state. Archiving hides their subtree from active browsing without changing every child flag; unarchive or a successful saved edit restores the relevant folder path. This preserves stored content and associations. See archival.

A node name is one segment of its descendants' paths, so renaming a folder, episode or file through PATCH /nodes/:id answers 400 for an empty name or one containing , or /, and leaves the tree unchanged. A Memo mount takes its name from the Memo.

On a server with the issue #1352 fix (not yet released), a move through PATCH /nodes/:id also keeps a node in its episode. A file or folder inside an episode moves only within that episode, a project-level node cannot move into an episode, and an episode stays at its project root. Any other move answers 400 and changes nothing. Renames are unaffected, and nested episodes are not supported. Older servers allowed these moves, after which the moved files dropped out of the episode's file list, the moved folder refused new files with 409, and an episode moved into a folder refused uploads with 403 while creating it by name made a second episode. Moving the node back to where it came from is still allowed and undoes this.

On a server with the issue #1360 fix (not yet released), a write-protected episode also refuses the generic node routes. POST /nodes into it (a file naming the episode, or a folder whose parentId is inside it), and PATCH /nodes/:id or DELETE /nodes/:id on the episode or anything inside it, answer 403 and change nothing. That covers renames, moves in or out, tags and metadata, and deleting a folder that holds a protected episode. PATCH /nodes/:id never sets an episode's writeProtected: sending that metadata key for an episode answers 400. Use PATCH …/episodes/:name to set or lift it. Project nodes are not covered, so renaming a project or deleting it (a soft delete) still works. The check covers what a generic node operation targets: the node, its source and destination, and the subtree it changes. It does not freeze a mounted resource itself. Renaming a memo or workflow through its own endpoint, or through its mount in another folder or project, still renames its mount inside a protected episode. Older servers enforced protection only on the episode's own file, track, log and parameter routes.

On a server with the issue #1365 fix (not yet released), a file's metadata.s3Key can be refused after its upload. Deleting a node queues its object for cleanup, and project files with the same bytes can share one key. Once cleanup has started on a key, the server never lets a node reference that key again, because the delete may complete at any later time. Use the objectKey from POST /namespaces/:slug/projects/:proj/upload-authorizations unchanged and treat it as opaque. It now ends in a generation (files/{projectId}/{sha256}/g000000000001), and the same bytes get a new generation after the previous one is retired.

  • 409 on POST /nodes or PATCH /nodes/:id. The key was retired between authorization and registration, or it is a hash-only key from an older server. Nothing is created or changed. Request a new authorization, upload the file again, and register the new key.
  • 409 on …/upload-authorizations/resume. The same condition applies. Start a fresh upload.
  • Unaffected writes. A request that writes back the key the same live node already holds is accepted.
  • Projects and episodes. They do not hold objects. A new metadata.s3Key sent to POST /nodes (kind=project or kind=episode), the project routes or the episode routes answers 400.
  • Episode file replacement. Replacing a file through POST /episodes/:id/files queues the replaced object for the same cleanup instead of deleting it.

The UI, CLI and Python SDK register once without retrying, so they report this 409 as an error. Running the upload again succeeds. Older servers could delete an object that a node registered moments earlier still pointed at, so that node's download failed.

On servers with batched cleanup enqueue, a folder or episode hard delete that exhausts its write-conflict retries returns 409 (OPERATION_CONFLICT) and rolls back its changes. Retry after concurrent writes settle. This does not retry expired transactions or change the project soft-delete contract.

Files

MethodPathDescription
POST/episodes/:id/filesUpload file (multipart)
GET/episodes/:id/filesList files
GET/episodes/:id/files/:fidFile metadata
GET/episodes/:id/files/:fid/downloadDownload file
PATCH/episodes/:id/files/:fidUpdate description, tags and metadata
DELETE/episodes/:id/files/:fidDelete file

All file routes require a logged-in caller. On a server with the issue #1351 fix (not yet released), the five routes other than upload also check access to the episode's project. Listing, metadata and download need read access: any role on the project, or any logged-in user when the project is public. PATCH and DELETE need the WRITE or ADMIN role, so a READ user gets 403. Without read access, these five routes answer 404 exactly as for an episode that does not exist. A deleted or write-protected episode still refuses PATCH and DELETE with 403. Older servers only checked that the caller was logged in. Upload is unchanged: it already required the WRITE or ADMIN role.

Tracks & Logs

MethodPathDescription
POST/episodes/:id/tracks/:name/appendAppend data point
POST/episodes/:id/tracks/:name/append-batchAppend batch
GET/episodes/:id/tracks/:name/dataRead track data
GET/episodes/:id/tracksList tracks
POST/episodes/:id/logsCreate log entries
GET/episodes/:id/logsQuery logs (level, time, search)

Parameters

MethodPathDescription
POST/episodes/:id/parametersSet/merge parameters
GET/episodes/:id/parametersGet parameters
DELETE/episodes/:id/parametersSoft-delete

Bindrs & Datasets

MethodPathDescription
POST/namespaces/:slug/projects/:proj/bindrsCreate a Bindr; returns { bindr }
GET/namespaces/:slug/projects/:proj/bindrsFull flat tree as { bindrs }; parent: null is top-level
GET/bindrs/:idBindr and a page of tagged nodes
GET/bindrs/:id/summaryMetadata only as { bindr }
PATCH/bindrs/:idUpdate metadata or parent; returns { bindr }
DELETE/bindrs/:idDelete the Bindr and its tags; children move to its parent
POST/bindrs/:id/membersTag one node using { nodeId }; returns { added, memberCount }
DELETE/bindrs/:id/membersUntag one node using { nodeId }; returns { removed, memberCount }
POST…/datasetsCreate dataset
GET…/datasetsList datasets
GET…/datasets/:nameGet dataset with bindrs
PATCH…/datasets/:nameUpdate dataset
DELETE…/datasets/:nameSoft-delete

Dataset paths are under /namespaces/:slug/projects/:proj/. Bindr item operations use stable IDs, not project/name paths. Resolve a display name from the project's flat Bindr list and refuse ambiguous matches before mutating.

Create accepts { name, description?, tags?, parent?, member?: { nodeId } }. parent is a Bindr ID or null; an omitted parent creates a top-level Bindr. The optional singular member seeds one node atomically with creation. There is no bulk members input. To tag more nodes, send one membership request per node; a sequence of such requests can partially succeed. Membership uses the file-tree node ID, not the resource ID it points to. Repeated add/remove requests are idempotent. Removing a tag does not delete its node or resource.

GET /bindrs/:id returns { bindr, members, page, pageSize, total, totalPages }; member rows expose nodeId. It accepts page, pageSize, resourceType, search, sort, and recursive=true (include descendant Bindrs). GET /bindrs/:id/summary does not read or count members. Both reads require access to the Bindr's project; a public project's Bindrs are readable without a token. An unreadable, missing or deleted Bindr produces the same status and error body.

A dataset name is unique among the project's live datasets; other projects may use the same name. Creating a dataset, or renaming one with PATCH, onto a live name answers 409 {"error": "dataset '<name>' already exists"} and changes nothing. DELETE is a soft delete: the dataset disappears from list and get, and its row keeps its id, name and deletion time, but it no longer holds the name — create and rename may both reuse it. Deleted datasets cannot be restored. This contract ships with a Dataset name index migration, and a deployment cannot take the release until that migration has run on its database. Servers released before it reserve a deleted dataset's name: create answers 409, and a rename onto any existing name, live or deleted, fails with 500.

Artifacts

Renderable, versioned documents with per-artifact visibility — the surface behind dl artifact. Public/list/read routes apply per-artifact policy themselves (member / public / valid share).

MethodPathDescription
GET/namespaces/:slug/artifactsCatalog list (members: all; others: public only). ?deleted=true lists the Trash (members)
GET/namespaces/:slug/artifacts/:idOne catalog row + viewerCanManage (?share= for share links)
POST/namespaces/:slug/artifacts/upload-credentialsMint scoped STS creds for a push (member)
POST/namespaces/:slug/artifacts/:idUpsert catalog entry — metadata / visibility / share token (member)
POST/namespaces/:slug/artifacts/read-tokenMint a short-lived per-artifact read token
GET/namespaces/:slug/artifacts/read/:token/*Read-proxy: stream artifact objects (Range-aware)
DELETE/namespaces/:slug/artifacts/:idSoft delete → Trash (member)
POST/namespaces/:slug/artifacts/:id/restoreRestore from Trash (member)
DELETE/namespaces/:slug/artifacts/:id/purgePermanent purge — storage + catalog, irreversible (member)
GET/me/artifactsSigned-in user's artifacts: yours + shared-with-you, tagged by group

For a display-title edit, POST title and the detail response's immutable resourceId as expectedResourceId to the immutable artifact ID. The catalog title and all live project filings commit together; name collisions or a stale identity return 409. The optional identity guard requires a title-only request and prevents a stale editor from creating a replacement catalog. Legacy metadata-only creation without this guard still starts at version 0. See artifact title and URL renames.

Scenes

Versioned scenes (MJCF + assets) — the surface behind dl scene. Scene 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-scene policy themselves; a hidden scene answers 404, never 403.

MethodPathDescription
GET/namespaces/:slug/scenesCatalog list (members: all; others: public only). ?deleted=true lists the Trash (members)
GET/namespaces/:slug/scenes/:nameOne catalog row + viewerCanManage + thumbVersion
GET/namespaces/:slug/scenes/:name/versionsAll pushed versions, newest first
GET/namespaces/:slug/scenes/:name/versions/:versionOne version's manifest — entry + per-file {path, size, hash, url} with presigned GETs (:version int or latest)
POST/namespaces/:slug/scenes/upload-credentialsMint STS creds scoped to envs/<ns>/<name>/ for a push (member)
POST/namespaces/:slug/scenes/:nameRegister a pushed version (create-or-revive, latestVersion = max), or patch title/description/envType/visibility (member)
POST/namespaces/:slug/scenes/:name/thumbnailStore the browser-captured PNG thumbnail, ≤ 512 KB (member)
DELETE/namespaces/:slug/scenes/:nameSoft delete → Trash (member)
POST/namespaces/:slug/scenes/:name/restoreRestore from Trash (member)
DELETE/namespaces/:slug/scenes/:name/purgePermanent purge — whole storage prefix + catalog, irreversible (member)

The old /envs API paths remain deprecated, method-preserving aliases with identical authorization and storage. Catalog responses include scenes and the legacy envs field. See Scenes compatibility.

Libraries

Asset collections stored verbatim under one storage prefix, searchable per asset — the surface behind dl 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.

MethodPathDescription
GET/namespaces/:slug/librariesCatalog list (members: all; others: public only). ?deleted=true lists the Trash (members)
GET/namespaces/:slug/libraries/:nameOne catalog row (LibraryDetail) + viewerCanManage
GET/namespaces/:slug/libraries/:name/manifestThe full parsed wire manifest (dreamlake.assets/v1), served verbatim
GET/namespaces/:slug/libraries/:name/assets/:assetIdOne asset with presigned per-file URLs — the preview payload (?ttlSeconds)
POST/namespaces/:slug/libraries/:name/files-presignPresigned GETs for manifest paths, ≤ 1,000 per batch — the pull payload (ttlSeconds)
GET/namespaces/:slug/libraries/:name/searchSearch inside one library (q, category, kind, license, tag, limit ≤ 200, offset)
GET/librariesVisible libraries across namespaces, newest first (limit ≤ 500)
GET/library-searchCross-library search over libraries=ns/a,ns/b (≤ 50); inaccessible targets land in skipped[]
POST/namespaces/:slug/libraries/:name/upload-authorizationsPresigned upload batch for a push (member)
POST/namespaces/:slug/libraries/:name/registerValidate the uploaded manifest, bump revision (CAS — stale expectedRevision → 409), reconcile storage (member)
POST/namespaces/:slug/libraries/:namePatch visibility / share token — content metadata is manifest-derived (member)
DELETE/namespaces/:slug/libraries/:nameSoft delete → Trash (member)
POST/namespaces/:slug/libraries/:name/restoreRestore from Trash (member)
DELETE/namespaces/:slug/libraries/:name/purgePermanent 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.

MethodPathDescription
GET/relay/providersWhich providers this deployment can relay to, and the base URL for each
POST/relay/:provider/v1/messagesRelay a chat completion (stream: true streams SSE straight back)
POST/relay/:provider/v1/messages/count_tokensRelay a token count
GET/relay/:provider/v1/modelsRelay the provider's live model list

Search

MethodPathDescription
POST/projects/:id/searchProject-wide vector search
POST/projects/:id/episodes/:eid/searchEpisode-scoped search
POST…/assets/searchSemantic search (CLIP text/image)

Health

MethodPathDescription
GET/healthServer status (no auth)

Next steps

CLI Reference →

The command-line wrapper over these endpoints.

Architecture →

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