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

# Entity map

> Every REST resource, every operation on it, where its IDs come from, and what is honestly not exposed — on one page.

This page maps the REST surface resource by resource: how to list, get,
create, update, and terminate each one, and — because most requests reference
other resources — exactly where each referenced ID comes from. Cells marked
**not exposed** are deliberate statements, not omissions; the
[gaps table](#not-addressable-with-an-api-key) collects them with the
supported alternative.

Two published surfaces serve these resources:

| Surface              | Base                         | Auth                            | Role                                                                         |
| -------------------- | ---------------------------- | ------------------------------- | ---------------------------------------------------------------------------- |
| Versioned operations | `https://useorgx.com/api/v1` | `Authorization: Bearer oxk_...` | The published contract — resources, commands, ledger reads, and projections. |
| App session routes   | assorted                     | Web-app session (browser)       | Human-authority actions: decision rulings, artifact acceptance.              |

The older polymorphic `/api/entities` route is a compatibility adapter. It is
documented separately for existing clients and is not part of the v1 OpenAPI
contract.

## Naming crosswalk

The same record can have a concept name and a wire name. This table is the
authority when the names differ:

| Concept name       | Wire name                                      | Note                                                         |
| ------------------ | ---------------------------------------------- | ------------------------------------------------------------ |
| Work item          | `task` (`?type=task`, `taskId`, `/tasks/{id}`) | Created by `POST /api/v1/work`, which returns `data.taskId`. |
| Episode            | `episode` (`GET /api/v1/episodes`)             | A read-only mission view. Mission IDs stay canonical.        |
| Agent run          | `run` (`?type=run`)                            | Distinct from an episode and from a discovery run.           |
| Discovery run      | `discovery-run`                                | A workflow-discovery pass, unrelated to an agent run.        |
| Agent work receipt | `agent-work-receipts` (portable, `receipt_id`) | Portable document imported through the receipt endpoint.     |
| Execution receipt  | `receiptId` in work responses                  | Workspace receipt returned by work commands.                 |
| Agent              | `agent` (`?type=agent`)                        | The built-in agent roster.                                   |

Where the wire uses `snake_case` (`task_id`, `receipt_id`) it is a request or
portable-document field; where it uses `camelCase` (`taskId`, `receiptId`) it
is a `/api/v1` response field. Both refer to the same records.

## Canonical v1 resources

These are the resources a new integration should build against. Every path in
this table is in the published OpenAPI document.

| Resource                                             | Read                                                           | Write                                              | Lifecycle / related operations                                                       |
| ---------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [Work item](/docs/api/entities/work-item)                 | `GET /work`, `GET /work/{taskId}`                              | `POST /work`                                       | `POST /work/{taskId}/complete`, `POST /lifecycle`                                    |
| [Initiative](/docs/api/entities/initiative)               | `GET /initiatives/{initiativeId}`                              | `POST /initiatives`, `POST /initiatives/proposals` | `GET /initiatives/proposals/{proposalId}`                                            |
| [Decision](/docs/api/entities/decision)                   | `GET /decisions`, `GET /decisions/{id}`                        | `POST /decisions`                                  | attention and resolution operations on `/decisions/{id}`                             |
| [Artifact](/docs/api/entities/artifact)                   | `GET /artifacts`, `/by-entity`, `/{artifactId}`                | `POST /artifacts`                                  | Human acceptance remains in the signed-in app; automated review uses artifact status |
| [Agent run](/docs/api/entities/run)                       | Run reads are exposed to the app; API keys control a known run | —                                                  | `POST /runs/{runId}/actions/{action}`                                                |
| [Operating process](/docs/api/entities/operating-process) | `GET /operating-processes`, `GET .../{processId}`              | `POST /operating-processes`                        | `POST .../confirm`, `POST .../activate`                                              |
| [Handoff](/docs/api/entities/handoff)                     | `GET /handoffs`, `GET .../{handoffId}`                         | `POST /handoffs`                                   | claim, fulfill, return, escalate, cancel                                             |
| [Discovery run](/docs/api/entities/discovery-run)         | `GET /discovery-runs`, `GET .../{runId}`                       | `POST /discovery-runs`                             | `POST .../{runId}/propose`                                                           |
| [Ledger event](/docs/api/entities/ledger-event)           | `GET /events/stream` or SSE                                    | —                                                  | Events are appended by accepted commands                                             |
| [Receipt](/docs/api/entities/receipt)                     | Work responses and validation metadata                         | `POST /agent-work-receipts`                        | Import is idempotent; validation can be account-free                                 |
| [Episode](/docs/api/entities/episode)                     | `GET /episodes`                                                | —                                                  | Read-only mission-compatible view                                                    |
| [Projections](/docs/api/entities/projections)             | `GET /projections/*`                                           | —                                                  | Derived reads with freshness metadata                                                |

## Compatibility-only entity reads

The polymorphic `/api/entities` route remains available for older MCP and
workspace integrations. It is not a v1 resource namespace and is not included
in the table above. Use it only when a legacy client requires a record that has
no dedicated v1 read.

| Compatibility record                                   | Read path                    | Write path                        |
| ------------------------------------------------------ | ---------------------------- | --------------------------------- |
| Workspace, goal, person, business, agent               | `GET /api/entities?type=...` | `POST`/`PATCH /api/entities`      |
| Workstream, milestone, blocker                         | `GET /api/entities?type=...` | Compatibility writes only         |
| Legacy task, initiative, decision, artifact, run reads | `GET /api/entities?type=...` | Prefer the dedicated v1 operation |

MCP column, condensed: `orgx_write` and `orgx_search` use the compatibility
adapter for records that do not yet have a dedicated MCP operation;
`orgx_act`, `orgx_decide`, and `review_artifact` carry human-authority flows;
`orgx_spawn` creates runs. Operating processes, handoffs, discovery runs,
episodes, the event stream, and projections are REST-first. The full mapping is
on the [MCP ↔ REST parity page](/docs/api/mcp-rest-parity).

## Where every ID comes from

| ID                           | Source of truth                                                                                                      |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `workspace_id`               | `GET /api/v1/me` → `data.default_workspace_id` or `data.workspaces[].id` — or omit it when the operation resolves it |
| `initiative_id`              | `POST /api/v1/initiatives` → `data.initiativeId`                                                                     |
| `workstream_id`              | `POST /api/v1/initiatives` → `data.workstreamId`; legacy lookup uses the compatibility adapter                       |
| `milestone_id`               | `POST /api/v1/initiatives` → `data.milestoneId`; legacy lookup uses the compatibility adapter                        |
| `taskId`                     | `POST /api/v1/work` → `data.taskId`                                                                                  |
| `expected_updated_at` (task) | `POST /work` → `data.task.updated_at`, or the task row's `updated_at`                                                |
| `expected_aggregate_version` | The previous command response (`data.aggregateVersion` / `meta.aggregateVersion`), or the resource's GET             |
| decision `id`                | `POST /api/v1/decisions` → `decision.id`                                                                             |
| artifact `id`                | `POST /api/v1/artifacts` → `artifact.id`                                                                             |
| `runId`                      | Returned by the execution system or a compatibility run read                                                         |
| `processId`                  | Client-generated at proposal, or the discovery propose flow; listed by `GET /api/v1/operating-processes`             |
| `handoffId`                  | `POST /api/v1/handoffs` → `data.id`                                                                                  |
| discovery `runId`            | `POST /api/v1/discovery-runs` → `data.run.id`                                                                        |
| `process_candidate_id`       | Discovery responses → `data.processCards[].processCandidateRef.id`                                                   |
| event `cursor`               | `GET /api/v1/events/stream` → `meta.nextCursor` (opaque; never constructed)                                          |
| `receiptId` / `eventId`      | Returned by every work command response                                                                              |
| `Idempotency-Key`            | You mint it — a stable string (≤200 chars) per logical operation                                                     |

## Not addressable with an API key

Honest inventory of what a developer credential cannot do today, with the
supported route:

| Capability                                                       | Status                           | Supported alternative                                                                                              |
| ---------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Hard-delete any record                                           | Not available through an API key | Use terminal statuses; MCP `orgx_act` supports the actions available to the connection                             |
| Resolve a decision (approve/decline)                             | Human session only (by design)   | Mission Control, or MCP `orgx_decide` under the signed-in user                                                     |
| Edit a pending decision's proposal fields                        | MCP only                         | Set the proposal fields at creation, or use MCP `orgx_write` while it is pending                                   |
| Accept or reject an artifact                                     | Human session only (by design)   | Machine reviewers write `eval_passed`; humans rule in the app                                                      |
| Create an agent run directly                                     | Not exposed                      | MCP `orgx_spawn`, Mission Control, or connected clients                                                            |
| Additional entity lifecycle actions                              | MCP only                         | Use `POST /api/v1/lifecycle`, the documented run actions, or the compatibility adapter when no v1 operation exists |
| List execution receipts                                          | Session only                     | Work command responses carry each `receiptId` and receipt row                                                      |
| Read or approve an initiative plan                               | Session only                     | The scaffold response and `GET /api/v1/initiatives/{initiativeId}` cover structure                                 |
| Deprecate or retire an operating process                         | Not available through an API key | Manage the process in the OrgX app                                                                                 |
| Run telemetry (activity, attention, questions, execution graphs) | MCP only                         | MCP tools `orgx_emit_activity`, `orgx_request_attention`, `orgx_request_question`, `orgx_emit_execution_graph`     |
| Delete a workspace                                               | Not available through an API key | Manage the workspace in the OrgX app                                                                               |
| Goal state metrics (`/api/v1/goals/*`)                           | Session only                     | Goal records are compatibility-only API-key records                                                                |

If an operation is absent from both this map and the
[OpenAPI document](https://useorgx.com/api/v1/openapi.yaml), treat it as
unsupported.