REST & WebSocket API¶

OpenCCU-Loom exposes a versioned REST API and a single multiplexed WebSocket stream for clients that want to read state, drive devices, and follow live changes without going through MQTT.

Base URL and transport¶

The REST API and the WebSocket endpoint share one HTTP listener. By default it binds :8119, so the base URL is:

http://<host>:8119/api/v1

The bind address is the north.rest.listen field in the config (default ":8119"); see Configuration. All REST paths below are relative to /api/v1.

Source of truth¶

Both surfaces are spec-driven. The published files in the repository are authoritative — this page is an orientation, not the contract:

When a field, status code, or schema differs between this page and those files, the files win.

Authentication¶

Most endpoints require authentication. A handful of routes are mounted outside the AuthRequire group by design — they either serve before any credentials exist (first-run) or must work for a logged-out client:

• GET /api/v1/info, GET /api/v1/health — public status probes.
• POST /api/v1/auth/login, POST /api/v1/auth/logout, GET /api/v1/auth/me — the SPA's login lifecycle (/auth/me is the startup probe; it returns 401 with no active session).
• GET /api/v1/setup/status, POST /api/v1/setup — first-run onboarding, unauthenticated because no admin exists yet.
• GET /api/v1/devices/{addr}/icon — device-model icon proxy, public like /health since it serves only non-sensitive artwork and must resolve from a bare <img> tag.
• GET /api/v1/auth/oidc/start, GET /api/v1/auth/oidc/callback — the OIDC redirect dance, only mounted when OIDC is configured.

See internal/north/rest/router.go for the authoritative route mounting. Everything else sits behind AuthRequire. Supported credentials are Basic auth, session cookies (after POST /auth/login), API tokens, and OIDC. Two role gates apply on top of authentication: an operator gate (op) for state-changing device calls, and an admin gate for system, user, and config administration. See Authentication and the Security guide for the full model.

Endpoint overview¶

The table groups the major endpoint families. Sample paths are illustrative; the OpenAPI file lists every path, parameter, and response schema.

WebSocket stream¶

Connect a WebSocket to:

ws://<host>:8119/api/v1/events

This is one multiplexed channel. The same connection carries command replies and topic broadcasts. The schema in assets/wsapi.json defines both invokable commands and server-pushed broadcasts in one commands array; run these against your checkout for the current counts rather than trusting a number here, since the catalogue grows every release: jq '[.commands[] | select(.kind!="broadcast")] | length' assets/wsapi.json for invokable commands, jq '[.commands[] | select(.kind=="broadcast")] | length' assets/wsapi.json for broadcasts.

Envelope¶

Every frame the daemon emits uses the same envelope:

Subscribe and resume¶

Send {"op":"subscribe", "topics":[...]} to start receiving broadcasts. The daemon echoes {"op":"subscribed", "topics":[...]} as an acknowledgement.

To resume after a reconnect, append since: N (your last seen seq). The daemon replays buffered events with seq > N matching your topics, then sends one control frame:

• {"op":"replay_done", "seq":N} — replay finished; seq is the last replayed value.
• {"op":"replay_lost", "oldest_seq":M} — since precedes the oldest buffered event; take a fresh GET /api/v1/snapshot to resync.

The replay buffer holds up to ~1024 events. Resume cursor and kind semantics are specified in ADR 0022.

Heartbeat and round-trip time¶

The daemon sends {"op":"ping", "echo":"<token>"} every 30 seconds and closes the connection if no frame arrives from you within 60. Respond with {"op":"pong"} to stay connected.

Copy the echo token back verbatim — {"op":"pong", "echo":"<token>"} — and the daemon times the round trip, reporting it on the following ping as rtt_ms:

{"op":"ping", "echo":"7", "rtt_ms":12.4}

That figure lets a client display its own latency to the daemon without measuring anything itself. It is absent on the first ping of a connection, and on every ping after a pong that carried no echo.

Two things to keep in mind:

• Echoing is optional. A bare {"op":"pong"} remains a valid heartbeat; the connection simply stays untimed. Clients written before this was added keep working unchanged.
• Treat the token as opaque. Its encoding is not part of the contract and will change without notice.

rtt_ms measures the distance between your client and the daemon — nothing else. It says nothing about the daemon's own link to the CCU, which is reported separately as the connection_latency_ms hub metric. The two are routinely orders of magnitude apart: a browser on the same LAN sees well under a millisecond here while the CCU round trip runs to several, and a client reached through a tunnel or a public host can invert that while the CCU link stays perfectly healthy. Never add them or present them as one number.

Example¶

const ws = new WebSocket("ws://localhost:8119/api/v1/events");

ws.onopen = () => {
  ws.send(JSON.stringify({ op: "subscribe", topics: ["devices/#"], since: lastSeq }));
};

ws.onmessage = (ev) => {
  const frame = JSON.parse(ev.data);
  if (frame.op === "ping") { ws.send(JSON.stringify({ op: "pong" })); return; }
  if (frame.op === "replay_lost") { /* GET /api/v1/snapshot and resync */ return; }
  if (frame.seq !== undefined) lastSeq = frame.seq;
  if (frame.kind) handleEvent(frame); // initial | change | refresh
};

Related reading¶

• External Client Wire Contract — the topic hierarchy and wire guarantees external clients depend on.
• MCP server — driving the daemon through the Model Context Protocol.
• MQTT topic schema — the parallel MQTT plane.