Skip to main content

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" } } via sendApiError.
  • Project-scoped routes take the project id in the path.
  • Async renders return 202 with a taskId, 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​

EndpointMethodDescription
/api/healthGET{ ok, version, dataRoot }
/api/versionGET{ version }
/api/app-configGET / PUTApplication configuration
/api/activeGET / POSTActive project + file (drives get_active_context)
/api/mcp/install-infoGETMCP client snippet, absolute node/CLI paths, existence flags
/api/agentsGETDetected coding-agent CLIs
/api/uploadPOSTGeneric image upload (max 8)
/api/dialog/open-folderPOSTNative folder picker
/api/projects-dirGET / PUTDefault projects folder
/api/projects-dir/migratePOSTMigrate projects to a new root

Projects​

EndpointMethodDescription
/api/projectsGETEvery project with computed display status
/api/projectsPOSTCreate — validates skillId and designSystemId (unknown → 400)
/api/projects/:idGETOne project
/api/projects/:idPATCHUpdate metadata / bindings / linked dirs
/api/projects/:idDELETEDelete, release the warm engine, revoke the tool token
/api/projects/:id/duplicatePOSTDuplicate
/api/projects/:id/linked-projectsPOSTLink sibling projects for context
/api/projects/:id/eventsGETActivity feed
/api/import/folderPOSTImport 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​

EndpointMethodDescription
/api/projects/:id/filesGETList, with ?since=<unix-ms> for cheap polling
/api/projects/:id/filesPOSTWrite ({ name, content, encoding }) or multipart upload
/api/projects/:id/files/*GETRead a file by path
/api/projects/:id/files/:nameDELETEDelete
/api/projects/:id/raw/*GET / DELETERaw byte access
/api/projects/:id/files/:name/previewGETPreview payload for the viewer
/api/projects/:id/files/:name/versionsGET / POSTVersion history; create a snapshot
/api/projects/:id/files/:name/versions/:versionIdGETRead a version
/api/projects/:id/files/:name/versions/:versionId/restorePOSTRestore a version in place
/api/projects/:id/searchGET?q= project search
/api/projects/:id/archiveGETZIP the project (or selected files via archive/batch)
/api/artifacts/savePOSTPersist an artifact
/api/artifacts/lintPOSTLint 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​

EndpointMethodDescription
/api/runsPOSTCreate a run → 202 { runId }
/api/runsGETList, filter by project / conversation / status
/api/runs/:idGETRun status
/api/runs/:id/eventsGETSSE event stream (?after=<lastEventId> to resume)
/api/runs/:id/cancelPOSTCancel
/api/chatPOSTLegacy 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​

EndpointMethodDescription
/api/skillsGETSkills, body stripped, hasBody flag
/api/skills/:idGETOne skill with body
/api/skills/:id/filesGETSide file listing
/api/skills/:id/file?path=GETRead a side file
/api/design-systemsGET / POSTList / create user-authored
/api/design-systems/:idGET / PATCH / DELETERead / update / delete (bundled → 403 DESIGN_SYSTEM_READ_ONLY)
/api/design-systems/:id/filesGETPackage file listing
/api/design-systems/:id/file?path=GETRead a package file
/api/brand-guidelinesGETLegacy alias of the same registry
/api/brand-guidelines/extractPOSTExtract a spec from a URL
/api/brand-guidelines/extract-githubPOSTStart a GitHub extraction (202 { runId })
/api/brand-guidelines/extract-github/:runIdGETPoll the job
/api/brand-guidelines/refinePOSTRefine a DESIGN.md body
/api/craftGETCraft reference slugs
/api/craft/:slugGETOne craft body

Media and motion​

EndpointMethodDescription
/api/media/modelsGETModels per surface, aspects, lengths, audioKinds
/api/media/configGET / PUTProvider configuration
/api/projects/:id/media/generatePOSTSubmit image/video/audio → 202 { taskId }
/api/projects/:id/media/sequencePOSTMulti-shot video → 202 { taskId }
/api/projects/:id/media/tasksGETTasks for a project
/api/media/tasks/:id/waitPOSTLong-poll { since, timeoutMs } (≤25s)
/api/media/motion/modelsGETMotion renderers + runtime readiness
/api/projects/:id/media/motion/generatePOSTRender 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​

EndpointMethodDescription
/api/live-artifactsGET / POSTList / create
/api/live-artifacts/:artifactIdGET / PATCH / DELETEManage
/api/live-artifacts/:artifactId/previewGETRendered preview
/api/live-artifacts/:artifactId/refreshesGETRefresh history
/api/live-artifacts/:artifactId/refreshPOSTTrigger a refresh

Deploy​

EndpointMethodDescription
/api/deploy/configGETDeploy configuration
/api/projects/:id/deployPOSTDeploy
/api/projects/:id/deploy/preflightPOSTPreflight checks
/api/projects/:id/deploymentsGETDeployment 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.

EndpointMethodDescription
/api/tools/live-artifacts/createPOSTCreate a live artifact
/api/tools/live-artifacts/listGETList live artifacts
/api/tools/live-artifacts/updatePOSTUpdate
/api/tools/live-artifacts/refreshPOSTRefresh
/api/tools/skills/filesGETList skill side files
/api/tools/skills/readGETRead a skill side file
/api/tools/skills/runPOSTExecute 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​

CodeMeaning
BAD_REQUESTMalformed body or params
PROJECT_NOT_FOUNDUnknown project id
UNKNOWN_SKILLskillId not in the registry
UNKNOWN_DESIGN_SYSTEMdesignSystemId not in the registry
DESIGN_SYSTEM_READ_ONLYAttempted write to a bundled system
DESIGN_SYSTEM_NOT_FOUNDUnknown user system
VERSION_NOT_FOUNDUnknown file version
INVALID_SKILL / INVALID_DESIGN_SYSTEMWrong type for the field
INTERNAL_ERRORUnhandled failure

Cross-origin policy​

Route familyPolicy
Read routesLocal same-origin; the daemon is bound to loopback
Media / motion generate + waitRejected on cross-origin (403)
Tool endpointsBearer token required
MCP install infoLocal 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.