Sessions and state

A stream session is the public unit of lifecycle and authorization.

type StreamSession = {
  id: string;
  type: string;
  owner: string;
  status: "starting" | "running" | "paused" | "stopped" | "failed";
  name: string | null;
  source: Record<string, unknown>;
  runtime: {
    connectedCount: number;
    activity: "empty" | "active";
    updatedAt: string;
  };
  connection: {
    signalingPath: "/signaling";
    room: string;
    accessToken: string;
  };
};

Display rules

• Treat connectedCount: 0 as an empty room, not a loading error.
• Display the source type and session name; do not infer the experience from media alone.
• Use status for lifecycle and runtime.activity for occupancy. They answer different questions.
• A running but empty session is valid and may be waiting for its first participant.
• Refresh state after pause, resume or restart; each action returns the updated session.

Ownership

Sessions are scoped to the API client derived from x-api-key. A client cannot list, read, mutate or delete another client’s sessions.