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.
In: header
Response Body
curl -X GET "https://example.com/v1/episodes"Episode item shape
Real item shape — id, summary, events, sealed
An episode is { id, scope, summary, events, started_at, ended_at, valid_from, valid_to, recorded_from, recorded_to, sealed }. Corrections from the v1 docs: id (not episode_id);
summary (not title; e.g. "Session of N events starting with: …"); events (not
event_ids); an undocumented sealed boolean; and there is no actors field.
The actor filter matches nothing; causal_chain is gated
Because episodes have no actors field, the actor query param matches nothing (actor=… → 200
with 0 items). The causal_chain appears only with with_causal_chain=true, and is a flat ordered
list [{ event_id }] — not the [{ from, to, relation }] edges the v1 docs showed.
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).
GET /v1/episodes/{id} returns 404
GET /v1/episodes/{id} does not resolve on v0.9.9 (404, with or without ?scope) — list
episodes via GET /v1/episodes and read the item you need from the list. (Contrast:
GET /v1/events/{id} and GET /v1/understanding/{id} do resolve.)