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


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