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 :8080, so the base URL is:

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

The bind address is the north.rest.listen field in the config (default ":8080"); 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¶

Every endpoint requires authentication except the three public ones:

• GET /api/v1/info
• GET /api/v1/health
• POST /api/v1/auth/login

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>:8080/api/v1/events

This is one multiplexed channel. The same connection carries command replies and topic broadcasts. The schema in assets/wsapi.json defines 98 command and broadcast entries.

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. The daemon also sends {"op":"ping"} heartbeats; respond with {"op":"pong"} to keep the connection open. Resume cursor and kind semantics are specified in ADR 0022.

Example¶

const ws = new WebSocket("ws://localhost:8080/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.