Live events

Use GET https://api.bibleit.app/v1/lives/{live_id}/events with live.get. Service tokens observe their organization; finite personal and delegated tokens observe only their owner’s personal Lives. This operator resource does not consume viewer seats.

Omit after for an immediate live.snapshot, including on reconnect. Responses have schema_version: 1, type, resource_type: "live", resource_id, Live sequence, opaque cursor and data. Snapshot data contains current safe Live, display, queue, per-Live viewer settings and audience-safe Studio design. Queue is null in presentation mode; presentation data excludes editable documents.

Send the previous cursor as after, with wait=0..25 seconds (default 25). A current difference returns live.changed; otherwise the poll waits and returns stream.heartbeat with null data if unchanged at the deadline. Repeat after each response. Allow timeout margin for normal server queue/response latency, and use an independent HTTP connection for writes if your client queues requests behind an outstanding poll.

The cursor compares current state; it is not a durable log position or an HTTP ETag. Studio revision changes can change the cursor without changing the Live sequence. Notifications may coalesce or be missed; no replay, gap-free delivery or exactly-once guarantee is promised. Reconnect without after to resynchronize, and check schema_version before interpreting an envelope.

Watches share the 50-per-Live operator cap with browser management connections, separately from audience capacity. Each HTTP poll uses admission budgets. Current credential identity, scopes, ownership and processing policy are checked after waits. Rotation, expiry or revocation can return 401; denied authority 403; movement/deletion 404 (or an already-revoked watch 403); dependencies 503. Idle authorization is checked every five seconds by default and at the poll deadline. No database transaction is held while waiting.