GET /v1/episodes
List episodes — consolidated narrative spans built from raw events.
Authorization
bearer PASETO v4 public token (or deployment gate key). Auth-disabled dev instances accept any caller. On a cluster data node a PASETO/JWT bearer (not the static key) gets 503 REVOCATION_UNAVAILABLE (retriable) on any route while the node's revocation lease has expired: the metadata group has not confirmed its revocation set for 10 s, or the node has just started. A single-node server never returns it.
In: header
Response Body
curl -X GET "https://example.com/v1/episodes"Episode item shape
An episode is { id, scope, summary, events, started_at, ended_at, valid_from, valid_to, recorded_from, recorded_to, sealed }: summary is text such as "Session of N events starting with:
…", events lists the member events, and sealed says whether it is closed. Episodes carry no
actors field, so filter by actor through the member events rather than an actor parameter. The
causal_chain appears with with_causal_chain=true, as an ordered list [{ event_id }].
Behavior notes
- Envelope:
{ items, next_cursor, has_more }.overlapping=<from>..<to>filters (200). POST /v1/episodes/build { scope }→{ built: N, items: [...] }forces a consolidation pass.- Episodes are sealed once consolidated — their
events[]becomes immutable (append-only model).
Read episodes from the list
There is no single-episode read: list episodes with GET /v1/episodes and take the item you need
from the list (GET /v1/episodes/{id} answers 404).