WebSocket API

The WebSocket endpoint at GET /api/ws provides real-time item events for web and mobile clients.

Connection

Connect with standard WebSocket. Authentication is handled via the same bearer token mechanism — the server resolves the token from the connection's auth context.

const ws = new WebSocket("ws://localhost:3000/api/ws");

ws.onopen = () => console.log("connected");

ws.onmessage = msg => {
  const event = JSON.parse(msg.data);
  // event: { org_id, kind, id }
};

ws.onclose = () => {
  // Reconnect after delay
  setTimeout(connect, 5000);
};

Event Format

All events are JSON with this structure:

{
  "org_id": "550e8400-e29b-41d4-a716-446655440000",
  "kind": "item.created",
  "id": "item-uuid"
}

Event Kinds

Kind	Fired when
item.created	New item inserted
item.updated	Item fields changed (title, status, tags, etc.)
item.answered	Form response submitted
item.dismissed	Item dismissed
item.archived	Item archived
bulk.updated	Multiple items changed in one operation
item.viewed	Item marked as viewed

Filtering

Events are filtered server-side by org_id. You only receive events for the organization associated with your auth token.

Ping/Pong

The server responds to WebSocket Ping frames with Pong. Use this for keepalive if your client library doesn't handle it automatically.

Implementation

The WebSocket handler uses a dedicated PgListener connection (separate from the pool) subscribed to the klaxon_events Postgres NOTIFY channel. This means events propagate across all server replicas — any replica can serve WebSocket connections.