Skip to content
ttorta docs

API Reference

API overview

What the board server is, where it binds, how it guards writes, and what shape every answer takes.

The server

The board that torta start runs is a plain Node HTTP server with no framework, and the terminal it serves in a pane is vendored into the package.

  • Default port: 5599. Change it with --port <n>.
  • Bind: loopback only. The banner prints the exact address.
  • Two modes: wizard, when the directory has no workspace, and board, when it does. When the wizard provisions, the same server flips to board mode on the same port.

Same origin, or refused

A request passes when it has no Origin header at all, or when its origin is http://localhost, https://localhost, http://127.0.0.1 or https://127.0.0.1, with any port.

Anything else gets status 403 and:

{ "ok": false, "error": "cross-origin requests are refused" }

The same check runs on the WebSocket upgrade.

Two audiences, two guards

Browser routes get the origin check and the loopback bind. The pane routes that can start a Claude Code session also carry a token guard.

The token is published in .torta/board.json when the board starts, and it is sent as the X-Torta-Token header. That file is not served, so no page and no agent can read it through the server. Without the token, status 403 and:

{
  "ok": false,
  "error": "this route is for the local watcher and needs the token from .torta/board.json"
}

Request and response shape

  • Request bodies are JSON. An empty body reads as {}. A body over 64 KB is refused, and a body that is not JSON is refused with the parser’s own message.
  • Responses are application/json with Cache-Control: no-store, except the static files, the vendored terminal and the event stream.
  • Most answers carry ok. A refusal carries ok: false and either error, a single sentence, or errors, an object keyed by the field at fault, with _ for a whole-request problem.

Status codes in use

Code When
200 the request was answered, including some refusals that are answers
400 the body or a field is wrong
403 cross-origin, or a pane route without the token
404 no such ticket, no such pane route, no such path
409 the wrong mode, or a state that makes the request impossible
500 the workspace could not be read or written

Where to go next