> ## 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.