Design — Reference

Design is served by design-api (design.destesi.io). All routes are workspace-scoped via the signed-in session; there is no separate API key surface in this release.

HTTP API

Account and setup

Method & path	Purpose
GET /v1/auth/me	Current user { id, email, name, workspace_id }.
GET /v1/me/products	Entitled products (powers the launcher).
GET /v1/setup/readiness	What still needs doing before Design is usable in this workspace — chiefly the GitHub connection.

Projects

Method & path	Purpose
POST /v1/projects	Create or import a project. Body { "name": "...", "repo": "owner/name"? } — omit repo to create a fresh repo.
GET /v1/projects	List the workspace’s projects.
GET /v1/projects/{id}	Fetch one project.
GET /v1/projects/{id}/sandbox	Sandbox state for a project.
POST /v1/projects/{id}/sandbox/reboot	Boot (or re-boot) the project’s sandbox.
GET /v1/projects/{id}/preview/*	Authenticated reverse proxy to the running app in the sandbox.

The Code tab

Method & path	Purpose
GET /v1/projects/{id}/files	The project’s file tree, read live from the running sandbox.
GET /v1/projects/{id}/files/content	The contents of one file.

Version history and restore

Method & path	Purpose
GET /v1/projects/{id}/history	The project’s commit history — every turn the agent committed.
POST /v1/projects/{id}/restore	Put the project back to an earlier commit.

History is a real safety net, not a log. Every successful agent turn is a commit, so the history is a list of the states your app has actually been in — and restore takes you back to any of them. That is what makes it safe to ask for an ambitious change: if the turn takes the app somewhere you don’t want, you restore the previous point rather than trying to talk the agent back out of it. Because the commits live in your own GitHub repo, you can equally do this with plain git outside Design.

Design system

Method & path	Purpose
GET /v1/projects/{id}/design-system	The project’s persistent brand tokens.
PUT /v1/projects/{id}/design-system	Replace them.

Design tokens persist across turns, so the agent keeps applying the same colors, type, and spacing instead of re-inventing a look every time you ask for a new screen.

The build feed

Method & path	Purpose
POST /v1/projects/{id}/chat	Run an agent turn. Body { "prompt": "..." }. Streams newline-delimited JSON stage events.
GET /v1/projects/{id}/runs	Paginated history of past turns. See below.

POST /v1/projects/{id}/chat responds with application/x-ndjson — one JSON object per line. The stage field is one of thinking, status, narration, tool, summary, committing, done, or failed:

{"stage":"thinking","run_id":"..."}
{"stage":"tool","tool":"read","path":"src/App.tsx","message":"Reading src/App.tsx"}
{"stage":"narration","message":"Adding the pricing grid"}
{"stage":"status","message":"Installing dependencies"}
{"stage":"summary","message":"Added a pricing page with three tiers."}
{"stage":"committing","message":"Saving to your GitHub repo"}
{"stage":"done","head_sha":"a1b2c3d","message":"changes committed"}

A tool event carries tool — one of read, edit, create, bash, or search — and the file path it’s acting on, which is what makes the feed readable as work rather than as a spinner. A failed turn ends with {"stage":"failed","error":"..."}. The HTTP write deadline is cleared for the duration of the turn, since the agent can be silent for minutes.

Turn history (GET /v1/projects/{id}/runs)

Your build feed is stored on the server, so it follows you between devices and browsers instead of living in one browser’s local storage. Opening a project loads the last 30 turns; scrolling up lazily loads older ones.

Parameter	Meaning
limit	Page size. Default 30, maximum 100.
before	Keyset cursor — an RFC 3339 (nanosecond) timestamp. Exclusive: the run at the cursor is not returned again.
before_id	The cursor’s run id (a UUID), which breaks ties between runs sharing a timestamp.

Pass both before and before_id together — they’re the next_before / next_before_id from the previous response. A malformed cursor returns 400 invalid_cursor rather than silently starting from the top.

{
  "runs": [ … ],
  "has_more": true,
  "next_before": "2026-07-30T11:04:22.418Z",
  "next_before_id": "…"
}

runs is ordered oldest to newest within the page, so a client can prepend a page above what it already shows.

Reloaded history is coarser than the live feed

History reconstructs the shape of each turn — your prompt, the agent’s summary, and whether it finished or failed. The granular tool and narration steps are live-only: you see them stream while a turn is running, and they aren’t replayed when you come back later.

Chat home

Design also has a chat home, separate from the per-project build feed, for finding and creating projects.

Method & path	Purpose
POST /v1/chat	Chat-home turn (NDJSON). Its tools create, list, and fetch projects.
GET /v1/conversations	List saved conversations.
GET /v1/conversations/{id}/messages	Page one conversation’s messages.
PATCH / DELETE /v1/conversations/{id}	Rename or delete a conversation.

Project lifecycle

A project carries an origin, a connect_repo (owner/name), a default_branch, and a snap_branch_id for its database. origin records where the code came from:

Origin	Meaning
created	Design created a fresh repository in your GitHub.
imported	You pointed Design at a repository you already had.
internal	You have no GitHub connection, so Design created the repository for you.

In every case the code lives in a real Git repository from the first commit — there is no sandbox-only mode and no export step.

Sandbox state machine

pending → cloning → booting → ready
                              ↘ failed
ready → (idle) → stopped → (reopen) → pending …

• pending — queued; the orchestrator will pick it up.
• cloning — repo archive fetched host-side and copied into the pod.
• booting — dependencies installed, dev server starting.
• ready — dev server healthy; the live preview is reachable.
• failed — a step errored; last_error explains why.
• stopped — idle-reaped; reopening re-boots from head_sha.

Environment variables (operators)

Var	Meaning
DESIGN_API_ADDR	Listen address (default :9108).
DESIGN_DATABASE_URL	Postgres DSN (schema design).
IDENTITY_API_URL	identity-api base (SSO + entitlements).
CONNECT_API_URL / CONNECT_CONTROLLER_SECRET	GitHub credential resolution.
DESTESI_API_URL / CONTROLLER_SECRET	Snap branch provisioning.
DESIGN_SANDBOX_ENABLED	1 to run the sandbox controller (needs a cluster + toolbox image).
DESIGN_SANDBOX_NAMESPACE / _TOOLBOX_IMAGE / _MODEL_SECRET / _NODEPORT_RANGE / _GATE_HOST_FMT	Sandbox runtime config.
DESIGN_WORKDIR / DESIGN_WORKING_BRANCH / DESIGN_AGENT_MAX_TURNS	Host-side git working clones, push branch, and agent turn cap.