Desk’s browser UI and CLI talk to a local HTTP server. The stock server has no built-in authentication, so the API is a local-trust surface. Default base URL:

​
Response shape

JSON routes return JSON with an appropriate status code. Errors are usually:
Unexpected failures are collapsed to a terse request failed response. Stack fields are redacted from JSON payloads.

​
Core routes

/api/desk returns the manifest-backed workspace snapshot. /api/system returns the cached system metrics snapshot. /api/pulse is the UI’s regular heartbeat. It includes system metrics, running session ids, attention state, unread event count, LSP status, and channel runtime state.

​
Session and layout mutation routes

Desk uses API routes for UI mutations such as:
  • add, edit, delete, move, reorder, and restart sessions
  • add, edit, delete, move, and reorder groups
  • add, edit, delete, move, and reorder projects
  • update group layout and persisted split sizes
The server validates cwd values, layout kinds, custom cell counts, and split-size percentages before writing the manifest.

​
Attention and agent events

Use /api/attention-read to mark events as read. Send { "clear": true } to the same route to clear the attention-event list. Agent hooks and plugins post typed events to /api/agent-event. Desk uses those events for attention, resume capture, and channel-engine release signals.

​
Terminal routes

Terminal capture accepts a durable sessionId, row count, and offset. It proxies the terminal daemon’s bounded emulator history and returns color-preserving lines for the frozen scrollback viewer. Live resize, repaint, input, and subscription traffic use the binary WebSocket rather than REST routes.

​
Terminal WebSockets

/ws/terminal is the only browser terminal path. One binary connection per browser tab carries multiple terminal surfaces. Hidden surfaces retain their channel under VISIBILITY false; the daemon rejects their input, ignores their resize authority, and sends no live output deltas. Same-channel reveal normally receives one bounded contiguous OUTPUT catch-up from its retained cursor. A cursor gap or terminal revision change receives a current-screen SNAPSHOT instead. Only actual surface removal or transport loss unsubscribes. Frames are channel- and generation-fenced through the supervised terminal daemon to the session’s Moor holder.

​
Filesystem routes

Filesystem routes live under /api/fs. They include:
  • home/root discovery
  • notes root and notes state
  • path validation
  • directory listing
  • file read and raw media read
  • download: one file as an attachment, or several files / a folder streamed as a .zip (GET /api/fs/download; GET /api/fs/download-plan is the validating pre-flight the explorer calls first, answering the archive name, byte total, entry count and how many unreadable entries were skipped). Archives are uncompressed (STORE) with per-entry data descriptors and keep empty folders; readers that scan strictly front-to-back without the central directory (Java’s ZipInputStream, funzip) cannot open them, everything that reads the central directory can. Selections beyond 65,535 members or 4 GiB are refused up front (no ZIP64).
  • filename and content search
  • write, create, rename, copy, and delete operations
  • LSP-aware preview/apply flows for create, rename, and delete
The server constrains paths to the active root, with a special allowance for the manifest file. Writes are atomic and mtime-guarded so external edits can produce a conflict instead of being silently overwritten.

​
Git routes

Git routes live under /api/git. They cover:
  • repository discovery
  • status and status maps
  • log/history
  • line diffs
  • worktree, index, commit, range, and branch diffs
  • stage and unstage
  • discard
  • commit and amend
  • fetch, pull, push, and publish
  • branch checkout, create, and delete
  • worktree removal
  • commit revert
  • GitHub repository and PR context
  • open-on-GitHub URL resolution
Desk runs the host git and gh commands and reports failures through JSON errors.

​
GitHub Projects routes

GitHub Projects routes live under /api/projects. They cover:
  • auth/scope checks
  • project listing
  • board data loading
  • item detail loading
  • owner listing
  • field value updates
  • item position changes
  • adding items by URL
  • draft item creation, edit, and conversion
  • archive, unarchive, and delete
  • status update create/delete
  • issue and pull request edits/comments/state changes
  • project create/edit/link-repo operations
The backend uses gh api graphql, gh issue, and gh pr.

​
Channels routes

Channels routes live under /api/channels. They cover:
  • channel state
  • engine diagnostics and actions
  • channel listing and message windows
  • threads
  • reactions
  • saved views
  • paused sessions
  • search
  • featured messages
  • uploads and file serving
  • activity events
  • export
  • message create, edit, and delete
  • member add and remove
  • share-to-channel
  • queue control
The CLI prefers these server routes when DESK_API is reachable, and falls back to direct markdown append for some post flows when the server is unavailable.

​
LSP routes and sockets

The HTTP endpoint requires a bearer token for session-scoped agent access. It validates file URIs against the configured workspace root and redacts sensitive command, environment, token, and path data from responses. The browser uses LSP wiring for editor features and diagnostics. Managed agents use the MCP wrapper described in Agent integrations.

​
Plugins

Plugins can add middleware, routes, and WebSocket upgrade guards for local embedders and downstream builds. See Security and plugin model before adding runtime extensions.

​
Next steps