The API

Everything the menu bar app can do, the API can do, and the app does it through the API. If it can be clicked it can be called — that is the first principle in the spec, and it is what lets Pteroprompter and the NativePHP app drive the same daemon the popover does.

Two transports, as equals

They are not alternatives and neither is the real one. One command set, one dispatcher, two framings: anything possible on one is possible on the other, and both are up whenever the daemon is. The ports are chosen only to stay clear of Sonocles’ 7357 and 7358 on the same machine.

Both are up from the moment rheocles-core starts, before any stream is armed or any take exists.

→ { "id": 7, "method": "GET", "path": "/", "query": {}, "body": null }
← { "id": 7, "status": 200, "body": { "name": "Rheocles", … } }

id is anything the client likes and is echoed back untouched; method, path, query and body are exactly the HTTP request’s; status is the HTTP status the same command would have produced. A JSON body is inline in body; a binary one — a preview JPEG — comes as base64 with its contentType instead. Events arrive on the same socket as objects with an event key and no id.

Authentication

A bearer token, always required, on every transport.

Authorization: Bearer <token>

The token is provisioned to ~/Library/Application Support/Rheocles/token, mode 0600, so any app running as you reads it and is paired with zero clicks. It is also shown in the popover’s settings as a pairing code, for anything that cannot read the file. POST /token/rotate (or the button beside the code) writes a new one and refuses the old from the next request on, both transports; a WebSocket that authenticated with the old token stays up but must auth again before its next command.

Loopback only in the MVP. The bind address and a certificate module are designed in, so LAN is an addition rather than a rewrite: v0.2 is TLS with a self-signed certificate and approve-on-the-box pairing — Rheocles announces on Bonjour, the capture box shows Allow Len’s MacBook?, one click pins the certificate and issues a token. Sonocles is being retrofitted to the same shape; one pairing design, two apps.

On each transport

const token = /* the token file, or the pairing code from the popover */
const ws = new WebSocket('ws://127.0.0.1:7448/')
ws.onopen = () => ws.send(JSON.stringify({ auth: token }))

const es = new EventSource(`http://127.0.0.1:7447/events?access_token=${token}`)

The command set

Preview

GET /preview/{stream} answers one frame, on demand. Nothing is captured when nobody is looking: each request opens the device, grabs a single frame, and closes it — as a polite second opener, with no configuration lock and no format change, so previewing a camera or a screen that a take is recording never disturbs the take. One preview runs at a time.

404 for an unknown stream; 503 no_frame if the device delivered nothing — a camera with no signal. Over the WebSocket a JPEG cannot ride in a JSON frame, so it comes back as base64 with its contentType:

← { "id": 16, "status": 200, "contentType": "image/jpeg", "base64": "/9j/4AAQSk…" }

The events

The same objects, byte for byte, on SSE and on every authenticated WebSocket. Each has an event key and no id.

Every one of these, with request fields, response examples, errors and the WebSocket frame, is on the API reference.

Conventions

• Paths are relative. The take folder to the output root — the one absolute path in the API, on GET / — and each file to the take folder. Clients store them as given.
• Ids are the handle. A take id, a stream id. Paths are what you get back when you ask.
• Absence is absence. An unmeasurable value is left out — freeBytes on a volume that will not say, drift on a display, framesDropped when none were. Never zero by default.
• Errors are one shape, { "error": "for humans", "code": "for_programs" }, on every route and both transports. HTTP carries the status in the status line, the WebSocket in the frame’s status. The codes are on the reference.
• CORS is open. A page in your browser can call the API; the token is the lock, not the origin.
• Same destination twice is a 409 conflict. Rheocles never silently suffixes. A take already recording is a 409 take_active.

The reference is generated

docs/openapi.yaml is hand-authored by the engine’s owner and is a first-class artifact: CI runs the real daemon and validates its live responses against the file, so “current with the code” is enforced rather than hoped. The reference page is built from that file at deploy time — every route, both transports (the WebSocket from its x-websocket block), every event — not copied from it, so it cannot drift either. It is also what a Saloon SDK is generated from.