Dashboard WebSocket API — Documentation

This socket tells an open dashboard that project data may have changed. It does not stream chat, job state, or durable audit results. After project_updated, the client fetches the relevant REST resource again.

Endpoint

wss://codegraph.example/api/v1/traceability/ws

Use ws only for a trusted local HTTP environment. Production pages served over HTTPS must use wss.

Authentication

Do not put a token in the URL. A query token is rejected with code 1008 and reason “Query token transport is not allowed”.

The server accepts the socket first and then waits up to 5 seconds for the first client message. Send exactly a JWT token object:

{"token": "<JWT>"}

The runtime also accepts a raw token string, but the JSON object is the documented contract. If authentication fails, the server sends an error event and closes with code 1008. If the first message does not arrive within 5 seconds, it closes with an authentication timeout.

An unauthenticated connection is allowed only when the explicit local-development unauthenticated-surface setting is enabled and both client and requested host are loopback addresses.

Events

Dashboard messages use event, not the type/payload envelope of the application WebSockets.

Events
event	When sent	Important fields
connected	Authentication and quota checks passed	client_id, heartbeat_seconds
heartbeat	No client message arrived before the heartbeat interval	timestamp, clients
project_updated	Audit, compliance, release, or another producer reports changed project data	project_name, trigger, timestamp
pong	Client sent the text ping	none
error	Authentication or message rate limit failed after accept	message

A project_updated event reports changed producer data. Request the authoritative result through the corresponding message or endpoint.

Browser example

function connectDashboardSocket(accessToken) {
  const scheme = location.protocol === "https:" ? "wss:" : "ws:";
  const socket = new WebSocket(
    scheme + "//" + location.host + "/api/v1/traceability/ws"
  );

  socket.addEventListener("open", () => {
    socket.send(JSON.stringify({ token: accessToken }));
  });

  socket.addEventListener("message", async (event) => {
    const message = JSON.parse(event.data);

    if (message.event === "project_updated") {
      await refreshDashboardResources(message.project_name);
    }
  });

  return socket;
}

Never log accessToken or embed it in the URL. Keep it only as long as required by the authenticated browser session.

Heartbeat and reconnect

The server sends heartbeat after the configured idle interval. A client may send the plain text ping and should receive a pong event.

Reconnect with bounded exponential backoff and jitter. Obtain a fresh token before reconnecting if the authenticated session expired. Do not reconnect continuously after code 1008: first correct authentication, configuration, or rate-limit conditions.

After reconnecting, reload dashboard resources through REST because events emitted while the socket was disconnected are not replayed.

Configuration

dashboard:
  websocket_enabled: true
  websocket_heartbeat_seconds: 30

The effective heartbeat is capped by the runtime WebSocket ping timeout. Configuration changes require the normal deployment/restart process for the installation.

Source contract

src/api/routers/dashboard_core/dashboard_ws.py — route, first-message authentication, events, heartbeat, and quota checks
src/config/runtime_sections/unified_config_dashboard.py — dashboard WebSocket settings
src/api/app_routers.py — /api/v1/traceability mount

For chat, job progress, and user notifications, use Application WebSocket API.