Episodes

Episodes are bounded, sealed spans of causally related events with a started_at / ended_at boundary. Built async by the consolidator; you can also trigger a build.

---

GET /v1/episodes

Capability: scope.read.local + traversal as appropriate.

GET /v1/episodes
  ?scope=org:acme/dept:eng
  &view=local
  &actor=user:alice
  &overlapping=2026-04-01..2026-05-01
  &with_causal_chain=true
  &limit=50
  &cursor=...

Response

{
  "items": [
    {
      "episode_id":  "ep_01HX...",
      "scope":       "org:acme/dept:eng",
      "title":       "Acme Q3 renewal POC",
      "started_at":  "2026-04-02T09:00:00Z",
      "ended_at":    "2026-04-29T17:00:00Z",
      "actors":      ["user:alice", "user:priya@acme"],
      "event_ids":   ["evt_01HX...", "evt_01HY..."],
      "causal_chain": [
        { "from": "evt_01HX...", "to": "evt_01HY...", "relation": "follows" }
      ],
      "valid_from":    "2026-04-02T09:00:00Z",
      "valid_to":      "2026-04-29T17:00:00Z",
      "recorded_from": "2026-04-02T09:00:12Z",
      "recorded_to":   null
    }
  ],
  "next_cursor": null,
  "has_more": false
}

---

GET /v1/episodes/

Returns the full episode record (single item from the list response).

---

POST /v1/episodes/build

Capability: scope.write

Force episode synthesis for a scope (normally runs async via the consolidator).

{ "scope": "org:acme/dept:eng/user:alice" }

Response

{
  "built": 12,
  "items": [ /* Episode records */ ]
}