> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Episode

> A read-only mission view for clients that use the episode resource name.

An episode is a read-only view of one mission — a contracted unit of agent
execution. The `/episodes` endpoint is a compatibility read for clients that
use the episode resource name; mission IDs remain the canonical identifiers.

<Note>
  Naming crosswalk: `compatibility.missionId` on each row is the underlying
  mission ID. Episodes and missions refer to the same execution record.
</Note>

## Wire shape

| Field | Type | Meaning |
| - | - | - |
| `id` | UUID | Episode (mission) ID. |
| `initiativeId` | UUID | The initiative the mission serves. |
| `workspaceId` | UUID | Tenant scope. |
| `ownerId` | UUID | Owning identity. |
| `state` | enum | Mission state — see vocabulary below. |
| `contract` | JSON object | The mission contract. |
| `contractDigest` | string | Digest of the contract. |
| `plan` | JSON object, nullable | The mission plan. |
| `planDigest` | string, nullable | Digest of the plan. |
| `aggregateVersion` | integer | Server-maintained version of the mission view. |
| `lastEventHash` | string | Opaque fingerprint of the latest state change. |
| `lastEventAt` | ISO datetime | When the projection last changed. |
| `compatibility` | object | `{ "source": "mission_v1", "missionId", "semantics": "mission_projection" }` |

State vocabulary: `DRAFT`, `CONTRACTED`, `PLANNING`, `READY`, `RUNNING`,
`WAITING`, `VERIFYING`, `REPAIRING`, `OUTCOME_PENDING`, `COMPLETE`,
`BLOCKED`, `FAILED`, `CANCELLED`, `COMPENSATED`, `REVOKED`.

## Operations

| Operation | Method + path | Auth | Params |
| - | - | - | - |
| List | `GET /api/v1/episodes` | API key/session | `workspace_id`, `limit` (1–50, default 50) |
| Get / create / update / delete | Not exposed | — | Episodes are read-only projections; missions change through the execution system, and their events appear on the [event stream](/docs/api/entities/ledger-event) as `mission.*` types. |

```bash theme={"dark"}
curl "https://useorgx.com/api/v1/episodes?workspace_id=3d7e4f5a-...&limit=20" \
  -H "Authorization: Bearer $ORGX_API_KEY"
```

Response: `{ "data": [ <episodes> ], "meta": { "apiVersion": "1",
"workspaceId", "count", "compatibility", ... } }`.

## Where the IDs come from

| Field | Obtain it from |
| - | - |
| episode `id` | The list response rows; equals `compatibility.missionId` |
| `initiativeId` | Cross-reference with `GET /api/v1/initiatives/{initiativeId}` |
| `workspace_id` | `GET /api/v1/me` → `data.default_workspace_id` or `data.workspaces[].id` |

## MCP equivalents

No MCP tool reads episodes today — this resource is REST-first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.