Endpoints & protocol

The hub has a LAN HTTPS surface for paired displays and data producers, and a localhost HTTP admin surface for MCP, the CLI, and local tools. The default ports are 8443 and 8444, respectively.

Widget JavaScript cannot call these endpoints directly. It uses the window.PREEN SDK, and the native app makes authenticated requests on its behalf. The SDK has no arbitrary URL proxy.

LAN surface

Authentication varies by operation. Session means a paired device’s bearer token; write means the hub’s producer/admin token. Pairing and WebSocket control use the handshakes described below.

The native SDK supplies the current widget id for db and trigger calls; widget code cannot select another id through those methods. Tokens themselves are not scoped to a single widget. A paired native client can access the hub’s widget library and datastores, while the write token can feed any widget and access any datastore. Keep both tokens out of widget HTML.

Streaming and WebSocket control

GET /api/data/:id/stream returns text/event-stream. Each data: event contains an envelope; the native app delivers only its data field to onData:

data: {"widgetId":"wgt_abc123","data":{"tempC":21.4},"ts":1788640000}

The hub sends the current snapshot if one exists, streams subsequent updates, and sends a comment heartbeat about every 15 seconds. There is no event-id replay history. The phone reconnects interrupted streams and also runs a roughly 10-second backup GET poll, so duplicate snapshot delivery is possible.

/control is a separate WebSocket. The hub sends a challenge nonce; the client responds with its device id and an HMAC made using the session token. After acceptance, the hub sends control messages such as active-widget selection, HTML reloads, and appearance changes. The raw token is not a WebSocket query parameter or authentication frame.

With Preen Plus, the native app carries requests, streamed data, and control messages through an end-to-end encrypted relay. The relay path uses sealed requests and a sealed control WebSocket, rather than exposing the LAN routes as ordinary public endpoints. The widget SDK behaves the same on both paths.

Admin surface (127.0.0.1, write token)

Every route below requires the write token. The listener is bound to loopback; MCP and the CLI are clients of this surface, and other local tools may use it.

There is no admin endpoint to approve consent. Registering capabilities does not arm them. Approval happens in the Mac app, including through its optional Auto-consent controls setting. See Interactive actions.

Mac Notch pairing, settings, alerts, and rules use /admin/surfaces and /admin/surfaces/:id, under the same write authentication. Each Notch is bound to one display; see the Mac Notch endpoint reference.

Discovery and TLS

service type:   _preen._tcp
domain:         local.

The LAN listener uses a self-signed HTTPS certificate. The native app pins its fingerprint when pairing. External producers need to trust the certificate; see TLS setup.

The iOS client chooses the route. The pairing QR supplies a local host and port, a certificate fingerprint, a one-time pairing token, and an optional relay base URL. An empty host supports relay-only pairing. Bonjour rediscovery uses the resolved address and advertised port; a candidate must authenticate with the saved certificate pin and session token before it replaces the saved endpoint.

With Local Network enabled, reconnect normally tries the saved address, an optional Wake-on-LAN retry, and Bonjour before relay. A recently working relay route or a pairing without a saved local address leads with relay. During a relay connection, the client probes for a verified local route before switching back. Disabled routes are skipped. See the connection guide for user controls.

PairResponse.relayBase supplies the relay address to save; when absent, the client retains the QR’s address for compatibility. Successful LAN connections refresh this through GET /api/relay. Its enabled and baseURL fields describe the Mac’s configuration, independently of uplink liveness. enabled: false clears the saved relay address. An advertised address alone does not establish Plus entitlement or relay admission.

POST /pair returns HTTP 401 with {"reason":"expired"} or {"reason":"invalid"} when the token is refused. The shared client preserves these reasons on LAN and relay. A relay handshake refusal may have no pairing reason body; clients must not assume it means the code expired. A pairing refusal ends the attempt and is separate from an established-session rejection.

Headers

Authorization: Bearer <token>     # authenticated HTTP routes
X-Preen-Schema: <version>         # wire schema metadata

Pairing supplies its one-time token in the request body. WebSocket control uses the challenge-response exchange above. Neither puts a token in the URL.

Timings