HTTP and WebSocket
The server's own interface, used by the editor, the CLI, the Omarchy widget and paired devices. The default address is http://127.0.0.1:29990. Agents should use MCP instead; it is the supported interface for them.
This page follows the contracts in docs/SPEC.md. Bodies are JSON unless the route says otherwise.
Access
- Without a token the server answers only on
127.0.0.1 or localhost at its own port, and refuses foreign Origin and Host headers and cross-site requests. - With
--token, every request needs Authorization: Bearer <token>. A browser can open /?token=<token> once instead. WebSocket upgrades may carry ?token=. - Routes marked this machine answer only a direct request from this computer: not a team member with the token, not a paired device, not a request through a proxy.
- On the Tailscale listener, everything needs the device token, and these answer nothing, token or not, since they configure this machine or start programs on it:
/api/peers, /api/runs, /api/run-settings, /api/comments, /api/omarchy, /api/live, /live-mcp, /api/notifications, /api/brands, /api/libraries, /api/code, /api/agents/steps, and /api/files/:id/ away, conflicts, libraries and brand.
Status and files
| Route | What it does |
|---|
GET / | The editor. |
GET /api/status | { version, port, files, agents: [{ name, fileId, fileName, status: 'working'|'idle', lastTool, at }] } |
GET /api/files | [{ id, name, updatedAt, thumbnail? }] |
POST /api/files {name?} | Makes a file: { id, name }. |
PATCH /api/files/:id {name} | Renames it. |
DELETE /api/files/:id | Deletes it. |
POST /api/files/:id/duplicate | Copies it. |
WS /sync/:fileId | The y-websocket protocol (sync and awareness). Works with the stock WebsocketProvider. |
Events
WS /events sends JSON messages:
| Message | When |
|---|
{t:'files'} | The list of files changed. |
{t:'activity', fileId, agent, tool, nodeIds, at} | An agent changed something. |
{t:'agent', runId, fileId, kind:'text'|'tool'|'done'|'error', text?, tool?} | Progress of a run. |
{t:'theme', theme} | The Omarchy theme changed. |
{t:'comment-run', fileId, threadId, runner, status, runId?, tool?} | A run from a comment: queued, working, done, failed or stopped. |
{t:'run-history', fileId} | The run history of a file changed. |
{t:'sync-conflicts', fileId} | Conflict notes changed. |
{t:'brand', id}, {t:'brand-report', fileId, runId, score, ...} | A brand changed; a run ended with a brand report. |
{t:'library', id} | A library was published, here or on another device. |
{t:'peers'} | Paired devices changed. |
Assets
| Route | What it does |
|---|
POST /api/assets | Raw body with its Content-Type. Returns { name, src: 'bogen-asset:<name>', url: '/assets/<name>' }. Up to 64 MB for images and fonts, 512 MB for video. |
GET /assets/:name | The asset. Answers Range, If-Range, If-None-Match and HEAD. |
Asset URLs in documents are bogen-asset:<name>. bogen-gen:<prompt> generates an image when it is written, with your own key.
Export
| Route | What it does |
|---|
POST /api/export {fileId, nodeIds, format, scale?, duration?, fps?, encoder?, svgMode?} | The file's bytes. format is png, jpg, webp, avif, svg, pdf, html, mp4 or webm. The report is in the X-Bogen-Export-Report header, URI-encoded JSON. |
POST /api/export/presets {fileId, nodeIds, presets:[{format, scale?|width?, suffix?}]} | A zip of several sizes. |
Snapshot, import and data
| Route | What it does |
|---|
POST /api/snapshot/site {url, fileId?, widths?, schemes?, limit?, captureFonts?} | NDJSON progress, ending with {t:'done', report}. |
POST /api/import/figma {url, token?, saveToken?, fileId?, name?} | The import report. |
GET|DELETE /api/config/figma | The saved Figma token. This machine. |
POST /api/data/fetch {url, path?, format?} | { records } from a public JSON or CSV address. |
History
| Route | What it does |
|---|
GET /api/files/:id/timeline | Commits and changes in one list. |
POST|GET /api/files/:id/commits, GET .../commits/:cid | Make and list commits; one commit. |
GET .../compare?from&to, GET .../compare/render?from&to&page | Compare two versions, as data or as a picture. |
POST .../changes/plan {ids?|run?} | What a revert would take back, and its conflicts. |
GET|POST .../branches, POST .../branches/:b/merge, DELETE .../branches/:b | Branches. |
POST .../git {action, dir?, message?, rev?} | The Git layer. This machine. |
GET .../folder, POST /api/files/import-folder | Design folders. |
GET /api/files/:id/away | What changed while nobody had the file open, once. |
GET /api/files/:id/conflicts, DELETE /api/files/:id/conflicts/:cid? | Conflict notes from sync. |
Agents and runs
| Route | What it does |
|---|
GET /api/runners | [{ id: 'claude'|'codex', available, version? }] |
POST /api/runs {fileId, pageId, nodeIds, prompt, runner, model?, effort?, review?} | Starts a run: { runId }, progress over /events. One run per file; a second gets 409. This machine. |
POST /api/runs/:id/stop | Stops it. |
GET /api/runs?fileId=, GET /api/runs/recent?limit=, POST /api/runs/:id/rerun {fileId} | Run history. |
GET /api/run-settings, PATCH /api/run-settings {runner, scope:'prompt'|'comment', model?, effort?, shareCursors?} | Model and effort choices. null clears; default means no flag. |
POST /api/agents/undo {fileId, agent} | Undoes an agent's last step. |
GET /api/agents/steps?fileId=, POST /api/agents/steps/undo {fileId, stepId}, GET /api/agents/steps/:id/preview?fileId=&which=before|after | The activity feed: steps, undo of one step, before and after pictures. |
POST /api/comments {fileId, text, author, threadId? | pageId?, nodeId?, x?, y?, model?} | Writes a comment: { threadId, messageId, started, refused? }. A mention starts or queues a run only for a direct request from this machine. |
GET /api/comments/runs?fileId= | Runs from comments in progress. |
Comments that a client writes into the document itself never start a run.
Live site mode
| Route | What it does |
|---|
GET|POST /api/live/sites, DELETE /api/live/sites/:id | Open and close live sites. |
POST /api/live/sites/:id/runs {prompt, runner, model?, effort?, element?} | A run on the project. |
/live-mcp/<token> | The file tools of one run; stops working when it ends. |
Brands
GET|POST /api/brands, GET|PUT /api/brands/default, GET|PATCH|DELETE /api/brands/:id, POST /api/brands/:id/duplicate, POST /api/brands/:id/versions, GET /api/brands/:id/diff?from=&to=, GET /api/brands/:id/impact, POST /api/brands/:id/apply, GET /api/brands/:id/brief, GET /api/brands/:id/sheet.html|sheet.png|guide.md|guide.pdf, GET|PUT /api/files/:id/brand, POST /api/files/:id/brand/check, POST|DELETE /api/files/:id/brand/waivers.
Code components and libraries
| Route | What it does |
|---|
GET /api/code/projects, POST /api/code/projects {dir, fileId?}, DELETE /api/code/projects/:id | Linked projects. Linking is from this machine only. |
GET /api/code/:project/components | Its components and props. |
POST /api/code/:project/measure | Measures a component. |
GET /api/code/:project/frame?file=&name= | The sandboxed frame, with a CSP sandbox. |
GET /api/libraries, GET /api/libraries/:id, GET /api/files/:id/libraries | Shared libraries. |
Omarchy and notifications
| Route | What it does |
|---|
GET /api/theme | { name, mode:'dark'|'light', vars: { '--ui-bg': '#...', ... }, font? }, or null when not on Omarchy. |
POST /api/omarchy/reload | Reads the theme again and broadcasts it. The theme hook calls this. |
GET|POST /api/omarchy/palette | The active palette as tokens. |
GET /api/notifications?since= | { seq, items }, for the bar widget. |
Device sync
Paired devices use /api/peer/... routes and a live link, among them GET /api/peer/timeline, .../timeline/:id/changes?device&after and .../timeline/:id/commit/:cid. Every request and socket carries X-Bogen-Version and X-Bogen-Features. These are for Bogen servers, not for scripts.
Also served
Routes the CLI and the editor use that the spec does not list:
| Route | Used by |
|---|
POST /api/snapshot {url, fileId?, pageId?, pageName?, name?, width?, height?, colorScheme?, captureFonts?} | bogen snapshot <url> |
GET|POST /api/peers, POST /api/peers/pair, POST /api/peers/tailnet, DELETE /api/peers/:id | bogen peer |
GET /api/fonts?q= | The font picker |
GET|POST|PATCH|DELETE /api/folders | Folders on the home screen |
POST /api/files/import, GET /api/files/:id/download | Opening and downloading .bogen files |
GET /api/files/:id/thumbnail | Thumbnails on the home screen |
GET /api/brands/templates, POST /api/brands/:id/template | Brand templates |
POST|GET|DELETE /mcp | MCP over Streamable HTTP |