Watch live dashboard events

EndpointCopy Anchor Link

GET /feed

Open a Server-Sent Events stream. Each frame has event: <name> and data: <JSON>, followed by a blank line. The initial frames contain roster and presence-view, then membership or membership-read-failed. Later frames carry roster, presence-view, membership, membership-read-failed and message updates. The stream provides no event IDs or replay cursor; reconnect and read history for backfill. An unhandled request failure after headers have been sent closes the stream. Membership read failures are sent as events and leave the stream open. The schemas under x-sse-events describe decoded data payloads.

Decoded payload schemas are also included under x-sse-events in the downloadable specification.

The message event forwards publisher JSON without wire-message validation. Treat msg.from as advisory; senderId is derived from the broker subject. A malformed publisher payload can still appear in the feed.

ParametersCopy Anchor Link

No operation parameters.

ResponsesCopy Anchor Link

HTTP 200Copy Anchor Link

An open UTF-8 SSE stream. Authentication and origin checks run before streaming begins.

Cache-Control: {"type":"string","const":"no-cache"}

Content type: text/event-stream.

{
  "type": "string"
}

Example:

event: roster
data: []

event: presence-view
data: {"state":"current","fresh":true}

HTTP 302Copy Anchor Link

A valid one-use k query token is exchanged for a dashboard session. The response redirects to the same path without its query. A valid existing cookie takes precedence over k.

Location: The requested path without the query string.

Set-Cookie: cotal_web_session=<session>; Path=/; HttpOnly; SameSite=Strict. The default local listener uses HTTP.

HTTP 401Copy Anchor Link

No valid session, an invalid launch token, or a spent launch token. The readiness credential does not authorize these routes.

Content type: application/json.

{
  "$ref": "#/components/schemas/AuthenticationError"
}

Example:

{
  "error": "unauthenticated"
}

HTTP 403Copy Anchor Link

Origin is checked before session authentication. An origin outside this listener's allowed origins is refused.

Content type: application/json.

{
  "$ref": "#/components/schemas/OriginError"
}

Example:

{
  "error": "cross-origin"
}

HTTP 413Copy Anchor Link

These read routes accept no request body. An announced body is refused before it is read; the connection is closed.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500Copy Anchor Link

The request failed. The body names the failure; a failed read does not terminate the dashboard.

Content type: application/json.

{
  "$ref": "#/components/schemas/Error"
}

Event payloadsCopy Anchor Link

Each named event carries the following JSON data schema.

{
  "roster": {
    "type": "array",
    "items": {
      "$ref": "#/components/schemas/RosterEntry"
    }
  },
  "presence-view": {
    "$ref": "#/components/schemas/PresenceView"
  },
  "membership": {
    "$ref": "#/components/schemas/Membership"
  },
  "membership-read-failed": {
    "type": "object",
    "properties": {
      "reason": {
        "type": "string"
      }
    },
    "required": [
      "reason"
    ]
  },
  "message": {
    "$ref": "#/components/schemas/LiveMessage"
  }
}

Authentication and access: HTTP interface of the @cotal-ai/web reference implementation. This description covers read operations, readiness metadata and the legacy channel deletion route; it does not establish a separate stable product or Cloud management API. Start the dashboard using the web service preset described in the operator guide. The server defaults to 127.0.0.1:7799; use the host and port configured for your dashboard.

Open the owner-private launch URL once to exchange its k query token for the cotal_web_session cookie. Keep the session on the same host. With the default bind, the permitted browser origins are http://127.0.0.1:<port>, http://localhost:<port> and http://cotal.localhost:<port>. A custom host uses its own HTTP origin. A cross-origin request is refused before session checks. The readiness nonce only opens /api/meta.

Read operations use GET and take no request body. Some read handlers also accept other bodyless methods; this description does not promise a 405 response for them. The native web service is read-only and always refuses channel deletion with 403. Legacy direct dashboard instances can enable deletion; /api/meta reports channelDeleteSupported. Description version 1 identifies this document, not the wire or npm package version.

OpenAPI specification contains the referenced response schemas. Complete Markdown reference.