Status Stream

Use GET /v1/events/conditions when an authenticated control-plane client needs condition changes between status snapshot refreshes. The stream is an optimization over snapshot reads, not their replacement.

Connect

curl --no-buffer --fail-with-body \
  -H "Authorization: Bearer $THALOVANT_TOKEN" \
  -H "Accept: text/event-stream" \
  https://api.thalovant.com/v1/events/conditions

The endpoint accepts comma-separated uids, kinds, namespaces, statuses, reasons, and types filters. A caller needs at least one supported hub, client, or ACL read scope.

Each condition event keeps the existing condition fields and adds an ordered stream envelope:

id: 1842
event: condition
data: {"version":1,"sequence":1842,"event_type":"upsert","resource":{"kind":"Hub","uid":"hub-uid","name":"primary","namespace":"tenant-a"},"resource_kind":"Hub","resource_uid":"hub-uid","type":"Ready","status":"True"}

Field	Meaning
SSE id	The PostgreSQL-backed public sequence, encoded as a decimal string.
version	Public status-event envelope version. The current version is 1.
sequence	The same numeric value as the SSE id.
event_type	upsert for an observation or delete for a durable removal observation.
resource	Stable kind and UID, plus the observed name and namespace.
Existing condition fields	The backward-compatible payload used by earlier clients.

Resume Safely

1. Store the last fully handled numeric sequence. Persist it only after your handler accepts the event.
2. Reconnect with the cursor. Send Last-Event-ID: 1842, or use ?last_event_id=1842 when the streaming client cannot set that header.
3. Process events in increasing sequence order. Ignore a sequence that is equal to or lower than the last handled value.
4. Refresh a status snapshot after cursor reset. Reconnect without the rejected cursor only after starting snapshot recovery.

Replay is ordered and bounded to 1,000 events. The API returns 409 with detail.code: status_cursor_expired when recovery would exceed that window. A cursor ahead of the persisted stream returns 409 with detail.code: invalid_status_cursor. These failures are explicit so a client does not silently skip status.

Note

During migration, a non-numeric legacy cursor is accepted as live-only. It cannot provide durable replay. Move to the numeric version-1 sequence as soon as the response includes X-Thalovant-Status-Stream-Version: 1.

The official Python, Node, Go, and Rust SDKs do not currently wrap this control-plane SSE endpoint. Use an HTTP streaming client that supports bearer authorization, SSE framing, reconnect cancellation, and bounded backoff.

Delivery Rules

• A duplicate watcher ingest does not allocate another public sequence.
• Sequence allocation and condition persistence commit in the same database transaction.
• Heartbeats are SSE comments and do not advance the cursor.
• Live fan-out can reconnect independently; replay comes from PostgreSQL.
• Periodic snapshot reads remain the recovery path for a rejected cursor, a long offline interval, or a client-side parsing failure.