Skip to main content
Artifacts are the versioned things people and agents make together in a workspace: multi-screen HTML projects, Dashboards backed by JSON collections, Slides read from a project, collaborative Designs, and native Word and Sheet documents edited through Craft. This page is the map of that API. It lists every route family, the switch that turns it on, the credentials it needs, the concurrency rule a client must follow and the error codes it can return. Request and response bodies for each operation are in the Pages API reference and in the generated OpenAPI document (tag pages).
Every Artifacts route lives under /api/v1/pages/... and uses the pages:read and pages:write credential scopes. The path prefix is a compatibility name: an artifact is stored as a Page row, so {slug} is the artifact’s slug, or @<id> for its ID. Pages as a product surface is being retired; Artifacts is the place to build on.

Feature switches

Projects are on by default; every other family on this page is off by default. A route family answers only when its switch is on for the workspace (or for the whole server). Turn a workspace flag on with crewship feature-flag enable <key>, which calls PUT /api/v1/feature-flags/{key}/override and needs a workspace OWNER or ADMIN. A server-wide switch is an environment variable read by the server; it turns the family on for every workspace. See Feature flags. The web UI has its own build-time switches. They only decide what the browser shows; the server still enforces the flags above. Each variable must equal true at build time.

Authentication and scopes

All routes need a signed-in human session or a CLI credential, plus a workspace (X-Workspace-ID header or workspace_id query). Workspace membership alone is not enough: each handler checks the caller’s current access to that one artifact inside the same transaction that reads or writes it. For supported Project tool operations, an admitted agent run acts on the owner’s behalf and remains bound to that artifact. Design tools act under the connected human’s current edit authority. These mandates never permit sharing a version. “Write access” means an edit grant; a comment grant only allows comments. A scoped CLI token is refused with 403 when it lacks the scope; unscoped tokens and browser sessions are not limited by scope. Agents work through MCP tools inside their crew rather than these routes. For project and Design tools the server rechecks the human’s consent, the artifact creation policy and the run’s binding to that one artifact on every call.

Versions and conflicts

Artifacts never overwrite silently. A lost race returns 409 with the stored state unchanged. Projects, Designs and Craft documents keep their versions in one version store: every save creates a new immutable version, numbered from 1, and restoring an old version creates a new version with the same content; nothing in history is deleted. Each family guards its writes differently.
  • Projects use compare-and-swap. A publish, restore or share must send the base_version it last read; if the latest version has moved, the server returns 409 artifact_version_conflict.
  • Shared version. The latest version and the shared version are separate. For Project, Dashboard and Slides, the owner and editors read latest; other readers get the shared version. Shared-only Design readers receive the shared snapshot on REST and WebSocket reads, even without an explicit version, plus presence. Live reads and document broadcasts require Edit authority or the separately audited administrative read path. Read-only credentials do not gain write authority.
  • Dashboard data is versioned per JSON document. Each write in a batch carries ifVersion (0 creates the document), and the batch names the project’s current base_version. One stale ifVersion fails the whole batch with 409 artifact_data_conflict. Writing data never creates a new project version.
  • Design has no base version. The server keeps one live Yjs document per Design and merges every change into it. Browsers send standard Yjs updates over GET /api/v1/pages/{slug}/design/ws; the server applies each update, stores the result and relays it to the other editors. Operations, snapshots, restore and share requests (and the agent’s design_apply tool) carry no base_version; they act on the current live state. Snapshots in the version store are taken on request, and automatically once edits have been idle for about ten seconds while an editor is connected. The server can still answer 409 “Design changed; reload and reapply” when the stored state moved during a request.
  • Craft allows one editor at a time through a lease. Acquiring a lease returns a generation; renew, release and handoff must send that exact generation. Every new holder gets a higher generation, so a request from a previous holder fails with 409 “native editor lease changed”. The lease lasts 15 seconds and is renewed by the editor’s live event stream (GET /api/v1/pages/{slug}/craft/events). Saves carry both the lease generation and the baseVersion they started from (Craft request bodies use camelCase field names).
When you get a 409, read the current state, decide what to keep, and send a new request against the new version. Never retry blindly with a newer base.

Quotas

When history is full, every existing version is kept and only new saves are refused. Read responses include a quota object with used_bytes, limit_bytes, warning (at 80% use) and retention. Owner retention is keep-all; a non-owner editor gets latest-version-only, and a reader limited to the shared version gets shared-version-only. Non-owners receive zero usage/limit values. Every artifact family also shares one workspace and instance storage budget. When that is full, writes answer 413 artifact_storage_quota, nothing is written and every existing version is kept. quota.storage_level warns in advance (near, critical, full) without byte counts. Workspace owners and admins read the byte counts from GET /api/v1/pages/artifacts/storage:
Too many concurrent uploads answer 503 artifact_storage_busy with Retry-After; retry the same request.

Route families

Projects

Dashboard data

A Dashboard is a project whose version declares JSON collections. Writing needs the same authority as saving a version: the owner, the owner’s consented agent run, or a human with a current Edit share or inherited folder write. A workspace role without a grant (ADMIN included) does not write, and an agent run acts only for the owner. base_version must be the latest version, otherwise 409. Read and Comment shares get 403; a caller who cannot see the Dashboard gets 404. Each written document records the writer as its updated_by, which the API projects as source_label.

Slides

Slides are read from a project version that follows the Slides profile.

Design

Craft documents

Craft is the native editor for Word and Sheet documents. The CLI side is documented in crewship craft. There is no separate export route: GET .../craft/document returns the bytes.

Agent guides

Static, versioned guides per artifact kind, embedded in the server. Any signed-in caller may read them; they read no workspace data and grant nothing. CLI: crewship artifacts kind-guide. These routes are not specific to one artifact type. They are documented on their own pages.

Error codes

Projects, Dashboards and Slides return JSON {error, code} for the cases a client must handle. Design and Craft return {error} only; branch on the HTTP status for those.