Entity map

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 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	`GET /work`, `GET /work/{taskId}`	`POST /work`	`POST /work/{taskId}/complete`, `POST /lifecycle`
Initiative	`GET /initiatives/{initiativeId}`	`POST /initiatives`, `POST /initiatives/proposals`	`GET /initiatives/proposals/{proposalId}`
Decision	`GET /decisions`, `GET /decisions/{id}`	`POST /decisions`	attention and resolution operations on `/decisions/{id}`
Artifact	`GET /artifacts`, `/by-entity`, `/{artifactId}`	`POST /artifacts`	Human acceptance remains in the signed-in app; automated review uses artifact status
Agent run	Run reads are exposed to the app; API keys control a known run	—	`POST /runs/{runId}/actions/{action}`
Operating process	`GET /operating-processes`, `GET .../{processId}`	`POST /operating-processes`	`POST .../confirm`, `POST .../activate`
Handoff	`GET /handoffs`, `GET .../{handoffId}`	`POST /handoffs`	claim, fulfill, return, escalate, cancel
Discovery run	`GET /discovery-runs`, `GET .../{runId}`	`POST /discovery-runs`	`POST .../{runId}/propose`
Ledger event	`GET /events/stream` or SSE	—	Events are appended by accepted commands
Receipt	Work responses and validation metadata	`POST /agent-work-receipts`	Import is idempotent; validation can be account-free
Episode	`GET /episodes`	—	Read-only mission-compatible view
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.

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, treat it as unsupported.

Getting Started

Connect Your Tools

Agent Ops

Platform

Build with the API

REST API v1 Reference

Entity Reference

Content Studio API

MCP and Plugins

Resources

Naming crosswalk

Canonical v1 resources

Compatibility-only entity reads

Where every ID comes from

Not addressable with an API key

​Naming crosswalk

​Canonical v1 resources

​Compatibility-only entity reads

​Where every ID comes from

​Not addressable with an API key

Naming crosswalk

Canonical v1 resources

Compatibility-only entity reads

Where every ID comes from

Not addressable with an API key