WebSocket

Secretary provides a WebSocket endpoint that pushes live event notifications to connected clients. This is used by the Web UI for its real-time log stream.

Endpoint

GET /api/ws

Upgrade to WebSocket. Authentication is required via the secretary_session cookie.

Authentication

The WebSocket endpoint validates the secretary_session JWT cookie. If the cookie is absent or invalid, the connection is closed with code 1008 (Policy Violation).

You must obtain a session cookie via POST /api/auth before connecting.

Message format

Every message is a JSON object:

{
  "topic": "trace.flush",
  "payload": { ... }
}

Topics

Topic	Description
`trace.flush`	A rule execution completed. Payload contains the execution trace.
`rules.reloaded`	Rule files were reloaded from disk.
`batch.started`	A batch run (rule against all documents) was started.
`batch.finished`	A batch run completed.

Usage example (JavaScript)

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

ws.addEventListener("message", (event) => {
  const { topic, payload } = JSON.parse(event.data);
  if (topic === "trace.flush") {
    console.log("New trace:", payload);
  }
});

The Web UI uses this endpoint to update the execution history view and log stream in real time without polling.