HTTP API
Everything the CLI, the web app, and the MCP servers do goes through the daemon's local HTTP API. If an integration needs a capability, it exists here first.
The daemon binds 127.0.0.1:7456 by default. Routes are unauthenticated for local same-origin requests; media, motion, and tool endpoints additionally reject cross-origin calls, and tool endpoints require a bearer token.
Conventions
- JSON in, JSON out. Errors are
{ "error": { "code", "message" } }viasendApiError. - Project-scoped routes take the project id in the path.
- Async renders return
202with ataskId, then are driven through/wait. - SSE for run streaming.
curl -s http://127.0.0.1:7456/api/health
# {"ok":true,"version":"1.3.2","dataRoot":"/Users/me/work/foo/.tfdesign"}
dataRoot is what lets a CLI decide whether to attach to a running daemon or boot its own.
System
| Endpoint | Method | Description |
|---|---|---|
/api/health | GET | { ok, version, dataRoot } |
/api/version | GET | { version } |
/api/app-config | GET / PUT | Application configuration |
/api/active | GET / POST | Active project + file (drives get_active_context) |
/api/mcp/install-info | GET | MCP client snippet, absolute node/CLI paths, existence flags |
/api/agents | GET | Detected coding-agent CLIs |
/api/upload | POST | Generic image upload (max 8) |
/api/dialog/open-folder | POST | Native folder picker |
/api/projects-dir | GET / PUT | Default projects folder |
/api/projects-dir/migrate | POST | Migrate projects to a new root |
Projects
| Endpoint | Method | Description |
|---|---|---|
/api/projects | GET | Every project with computed display status |
/api/projects | POST | Create — validates skillId and designSystemId (unknown → 400) |
/api/projects/:id | GET | One project |
/api/projects/:id | PATCH | Update metadata / bindings / linked dirs |
/api/projects/:id | DELETE | Delete, release the warm engine, revoke the tool token |
/api/projects/:id/duplicate | POST | Duplicate |
/api/projects/:id/linked-projects | POST | Link sibling projects for context |
/api/projects/:id/events | GET | Activity feed |
/api/import/folder | POST | Import an existing folder as a project |
Create body highlights:
{
"id": "board-deck-1a2b3c4d",
"name": "Board deck",
"skillId": "pptx-svg-export",
"designSystemId": "linear-app",
"metadata": { "kind": "deck" },
"pendingPrompt": "A board deck…"
}
skillId and designSystemId are resolved against the live registries. An unknown value is 400 UNKNOWN_SKILL / 400 UNKNOWN_DESIGN_SYSTEM — never a silent null. This is what makes the CLI's --skill and --design-system trustworthy.
Files
| Endpoint | Method | Description |
|---|---|---|
/api/projects/:id/files | GET | List, with ?since=<unix-ms> for cheap polling |
/api/projects/:id/files | POST | Write ({ name, content, encoding }) or multipart upload |
/api/projects/:id/files/* | GET | Read a file by path |
/api/projects/:id/files/:name | DELETE | Delete |
/api/projects/:id/raw/* | GET / DELETE | Raw byte access |
/api/projects/:id/files/:name/preview | GET | Preview payload for the viewer |
/api/projects/:id/files/:name/versions | GET / POST | Version history; create a snapshot |
/api/projects/:id/files/:name/versions/:versionId | GET | Read a version |
/api/projects/:id/files/:name/versions/:versionId/restore | POST | Restore a version in place |
/api/projects/:id/search | GET | ?q= project search |
/api/projects/:id/archive | GET | ZIP the project (or selected files via archive/batch) |
/api/artifacts/save | POST | Persist an artifact |
/api/artifacts/lint | POST | Lint artifact HTML |
Writes to .html files record a manual version snapshot automatically, so a save in the app immediately contributes to history.
Runs and streaming
| Endpoint | Method | Description |
|---|---|---|
/api/runs | POST | Create a run → 202 { runId } |
/api/runs | GET | List, filter by project / conversation / status |
/api/runs/:id | GET | Run status |
/api/runs/:id/events | GET | SSE event stream (?after=<lastEventId> to resume) |
/api/runs/:id/cancel | POST | Cancel |
/api/chat | POST | Legacy single-shot chat stream |
tfdesign run --format json is a thin projection of this stream: round_start, text_delta, tool_use, round_end, question_form, result, error. Reconnection is supported with after= and bounded retries, which is why a dropped connection does not lose a run.
Catalogs
| Endpoint | Method | Description |
|---|---|---|
/api/skills | GET | Skills, body stripped, hasBody flag |
/api/skills/:id | GET | One skill with body |
/api/skills/:id/files | GET | Side file listing |
/api/skills/:id/file?path= | GET | Read a side file |
/api/design-systems | GET / POST | List / create user-authored |
/api/design-systems/:id | GET / PATCH / DELETE | Read / update / delete (bundled → 403 DESIGN_SYSTEM_READ_ONLY) |
/api/design-systems/:id/files | GET | Package file listing |
/api/design-systems/:id/file?path= | GET | Read a package file |
/api/brand-guidelines | GET | Legacy alias of the same registry |
/api/brand-guidelines/extract | POST | Extract a spec from a URL |
/api/brand-guidelines/extract-github | POST | Start a GitHub extraction (202 { runId }) |
/api/brand-guidelines/extract-github/:runId | GET | Poll the job |
/api/brand-guidelines/refine | POST | Refine a DESIGN.md body |
/api/craft | GET | Craft reference slugs |
/api/craft/:slug | GET | One craft body |
Media and motion
| Endpoint | Method | Description |
|---|---|---|
/api/media/models | GET | Models per surface, aspects, lengths, audioKinds |
/api/media/config | GET / PUT | Provider configuration |
/api/projects/:id/media/generate | POST | Submit image/video/audio → 202 { taskId } |
/api/projects/:id/media/sequence | POST | Multi-shot video → 202 { taskId } |
/api/projects/:id/media/tasks | GET | Tasks for a project |
/api/media/tasks/:id/wait | POST | Long-poll { since, timeoutMs } (≤25s) |
/api/media/motion/models | GET | Motion renderers + runtime readiness |
/api/projects/:id/media/motion/generate | POST | Render a composition → 202 { taskId } |
generate validates before queueing: unknown model, cross-surface model, unavailable model, or a non-speech audio kind all 400 immediately with the legal values named.
The /wait snapshot:
{
"taskId": "…",
"status": "running" | "done" | "failed",
"progress": ["…new lines since `since`…"],
"nextSince": 12,
"file": { "name": "hero.png", "size": 1843200, "mime": "image/png" },
"motion": { "fps": 30, "duration": 6, "frames": 180, "hasAudio": false },
"error": { "message": "…", "status": 502 }
}
motion is present only for motion renders.
Live artifacts
| Endpoint | Method | Description |
|---|---|---|
/api/live-artifacts | GET / POST | List / create |
/api/live-artifacts/:artifactId | GET / PATCH / DELETE | Manage |
/api/live-artifacts/:artifactId/preview | GET | Rendered preview |
/api/live-artifacts/:artifactId/refreshes | GET | Refresh history |
/api/live-artifacts/:artifactId/refresh | POST | Trigger a refresh |
Deploy
| Endpoint | Method | Description |
|---|---|---|
/api/deploy/config | GET | Deploy configuration |
/api/projects/:id/deploy | POST | Deploy |
/api/projects/:id/deploy/preflight | POST | Preflight checks |
/api/projects/:id/deployments | GET | Deployment list |
Tool endpoints (token-authed)
These are the agent-facing writes. They require Authorization: Bearer <OD_TOOL_TOKEN> and are scoped to the token's project.
| Endpoint | Method | Description |
|---|---|---|
/api/tools/live-artifacts/create | POST | Create a live artifact |
/api/tools/live-artifacts/list | GET | List live artifacts |
/api/tools/live-artifacts/update | POST | Update |
/api/tools/live-artifacts/refresh | POST | Refresh |
/api/tools/skills/files | GET | List skill side files |
/api/tools/skills/read | GET | Read a skill side file |
/api/tools/skills/run | POST | Execute a skill script |
curl -s -X POST http://127.0.0.1:7456/api/tools/skills/run \
-H "authorization: Bearer $OD_TOOL_TOKEN" \
-H 'content-type: application/json' \
-d '{"skillId":"pptx-svg-export","script":"scripts/svg_to_pptx.py","args":["--out","deck.pptx"]}'
Tool tokens come in two lifetimes: a 15-minute chat token and a 12-hour engine token minted once per warm engine, because the engine outlives the chat. Engine tokens are revoked when the project is deleted or the engine is released.
Error codes
| Code | Meaning |
|---|---|
BAD_REQUEST | Malformed body or params |
PROJECT_NOT_FOUND | Unknown project id |
UNKNOWN_SKILL | skillId not in the registry |
UNKNOWN_DESIGN_SYSTEM | designSystemId not in the registry |
DESIGN_SYSTEM_READ_ONLY | Attempted write to a bundled system |
DESIGN_SYSTEM_NOT_FOUND | Unknown user system |
VERSION_NOT_FOUND | Unknown file version |
INVALID_SKILL / INVALID_DESIGN_SYSTEM | Wrong type for the field |
INTERNAL_ERROR | Unhandled failure |
Cross-origin policy
| Route family | Policy |
|---|---|
| Read routes | Local same-origin; the daemon is bound to loopback |
| Media / motion generate + wait | Rejected on cross-origin (403) |
| Tool endpoints | Bearer token required |
| MCP install info | Local same-origin only |
The daemon is a local, single-user service. It is not designed to be exposed on a network interface; --host exists for restricting access to a specific address (a Tailscale IP, for example), not for publishing it.