Compatibility entities

/api/entities is the legacy general read/write surface over workspace records. One endpoint serves every entity type — initiatives, workstreams, milestones, tasks, decisions, artifacts, runs, goals, and more — selected by a type parameter. Existing MCP and workspace integrations may still use it.

https://useorgx.com/api/entities

This endpoint lives outside the /api/v1 namespace and outside the published OpenAPI document. It is retained for compatibility only. New integrations should use the dedicated /api/v1 operation for the resource they need; the OpenAPI document is the machine contract.

Authentication

All three methods require a personal API key or an authenticated MCP connection:

Authorization: Bearer oxk_...

With an API key, reads and writes are scoped to the key owner’s records. The user_id parameter must match the key’s identity; a mismatch returns 403.

Methods

Method	Purpose
`GET`	List or fetch records by `type`
`POST`	Create one record
`PATCH`	Update one record by `type`+`id`

There is no DELETE method on this endpoint. See deletion and terminal states.

Entity type vocabulary

The type parameter accepts these values. Each maps to one underlying table; the label and body columns show which field names the type actually stores (generic title/name and summary/description aliases are mapped for you on write).

`type`	Label field	Body field	Status field + values
`initiative`	`title`	`summary`	`status`: draft, active, blocked, paused, completed, archived
`workstream`	`name`	`summary`	`status`: not_started, active, blocked, paused, completed
`milestone`	`title`	`description`	`status`: planned, in_progress, completed, at_risk, cancelled
`task`	`title`	`description`	`status`: todo, in_progress, done, blocked
`stream`	`name`	`description`	`status`: pending, ready, active, blocked, completed, failed, paused
`project`	`name`	`description`	`status`: draft, active, archived
`objective`	`title`	`description`	`status`: active, paused, completed, archived
`decision`	`title`	`summary`	`status`: pending, approved, declined, superseded, cancelled (plus legacy `rejected`)
`artifact`	`name`	`description`	`status`: draft, in_review, approved, changes_requested, superseded, archived, eval_passed, rejected
`run`	`title`	`summary`	`status`: draft, planned, awaiting_approval, running, blocked, paused, completed, failed, cancelled, archived
`blocker`	`title`	`description`	`status`: open, resolved, dismissed
`goal`	`title`	`description`	`status`: draft, active, at_risk, blocked, achieved, missed, descoped, pivoted
`person`	`display_name`	`description`	`relationship_stage`: stranger, prospect, conversation, design_partner, active_client, paused, churned, alumni
`business`	`legal_name`	`description`	`engagement_stage`: unknown, qualified, engaged, active, paused, churned, alumni
`relationship`	`role_title`	`description`	`relationship_lifecycle_stage` (checked at the database)
`workspace`	`name`	`description`	none
`playbook`	`title`	`description`	`status`: draft, active, archived
`workflow`	`name`	`description`	`status`: draft, active, paused, completed
`skill`	`name`	`description`	`status`: draft, active, archived
`plan_session`	`title`	`description`	`status`: active, completed, abandoned
`prospect`	`name`	`description`	`status`: identified, engaged, qualified, audit_booked, audit_completed, closed_won, closed_lost, archived
`opportunity`	`name`	`description`	`status`: draft, qualified, audit_scheduled, audit_completed, offer_made, closed_won, closed_lost
`bug_report`	`title`	`description`	`status`: open, triaged, in_progress, resolved, closed, wont_fix
`launch_checkpoint`	`name`	`description`	`decision`: pending, go, hold, fallback
`studio_brand`	`name`	`description`	`ingestion_status`: pending, processing, ready, failed
`studio_content`	`title`	`description`	`status`: pending, generating, ready, failed, exported

Two additional read-only types are served without a table lookup: agent (the built-in agent roster, filterable by domain) and video_template. The alias issue is accepted and normalized to blocker.

GET — list and fetch

curl "https://useorgx.com/api/entities?type=task&status=in_progress&limit=20" \
  -H "Authorization: Bearer $ORGX_API_KEY"

curl "https://useorgx.com/api/entities?type=initiative&include_relationships=true&count=true" \
  -H "Authorization: Bearer $ORGX_API_KEY"

Query parameters

Parameter	Meaning
`type`	Required. One of the vocabulary values above.
`id`	Fetch one record.
`ids`	Comma-separated UUID list, up to 100.
`status`	Filter on the type’s status field; must be one of that type’s valid values.
`initiative_id`	Scope filter for `milestone`, `workstream`, `stream`, `task`, `decision`, `run` (and artifact metadata matches).
`workstream_id`	Scope filter for `task` (and artifact metadata matches).
`workspace_id`	Workspace scope (UUID). Rows without a workspace remain visible for supported types.
`search` (alias `query`)	Case-insensitive text match over the type’s label and body fields.
`fields`	Comma-separated column subset; `id` is always included.
`limit`	Default 20, maximum 100.
`offset`	Default 0.
`order_by`	One of `created_at`, `updated_at`, `sequence`, `due_date`, `priority`, `status`, `title`, `name`, or `natural` (hierarchy types only).
`order_direction`	`asc` or `desc` (default `desc`).
`include_relationships`	`true` to embed child rows (for example an initiative’s workstreams, milestones, and tasks).
`count`	`true` to compute `pagination.total`; otherwise `total` is `-1`.

Response envelope

{
  "type": "task",
  "data": [
    {
      "id": "6f4e8a34-9f2f-4a3e-8d5b-2f1c9f7f2e1a",
      "title": "Review the launch plan",
      "status": "in_progress",
      "milestone_id": "0a4b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
      "workstream_id": "1b5c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
      "initiative_id": "2c6d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
      "priority": "medium",
      "created_at": "2026-08-18T16:04:11.000Z",
      "updated_at": "2026-08-19T09:12:45.000Z",
      "workspace_id": "3d7e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a"
    }
  ],
  "ordering": { "order_by": "created_at", "order_direction": "desc" },
  "pagination": { "total": -1, "limit": 20, "offset": 0, "has_more": false }
}

POST — create

The body is flat: type plus the record’s fields. owner_id defaults to the API key’s identity.

curl https://useorgx.com/api/entities \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "initiative",
    "title": "Q3 onboarding revamp",
    "summary": "Reduce time-to-first-work for new workspaces.",
    "idempotency_key": "onboarding-revamp-2026q3"
  }'

Creation rules that matter:

Initiative idempotency. idempotency_key (up to 120 characters) replays the existing initiative with _dedup: true and _replayed: true instead of inserting a duplicate.
Hierarchy dedup. Creating a workstream, milestone, or task whose label already exists (case-insensitive) inside the same parent scope returns the existing row with _dedup: true rather than a sibling duplicate.
Hierarchy parents. workstream requires initiative_id; task and milestone resolve their parents from milestone_id / workstream_id / initiative_id.
Guarded types. blocker creation is refused here (blockers are raised by runs). decision creation may not set a non-pending status or any server-owned resolution field. run creation may not set status, started_at, completed_at, or cancelled_at. artifact creation may not set approved or rejected — those assert a human ruling; an automated reviewer writes eval_passed instead.

The success envelope is { "type": ..., "data": { ... } } with the created row in data (also spread at the top level for older clients). Its data.id is the UUID you use everywhere else.

PATCH — update

The body is flat: type, id, plus the fields to change.

curl https://useorgx.com/api/entities \
  -X PATCH \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "task",
    "id": "6f4e8a34-9f2f-4a3e-8d5b-2f1c9f7f2e1a",
    "status": "in_progress",
    "priority": "high"
  }'

Update guards, enforced per type:

Decision: proposal-field updates are available through the MCP decision tool while a decision is pending; a personal API key receives 403. Only proposal fields (title, summary, description, priority, due_at, recommended_action, blocks_task, estimate, urgency, urgency_score) are patchable, and only while pending (409 otherwise). Approving or declining is a human action — see the decision page.
Run: status and timestamp fields are rejected (403); control a run through POST /api/v1/runs/{runId}/actions/{action}.
Blocker: not patchable at all; blockers close through their resolve and dismiss lifecycle.
Artifact: approved and rejected are rejected (403); a machine reviewer writes eval_passed.
Task: done tasks are terminal for automated updates; a 409 tells you to reopen deliberately first.

Deletion and terminal states

/api/entities has no DELETE method, and hard deletion is not part of the API-key REST contract. Use terminal statuses for API-key workflows. The MCP orgx_act tool can perform the additional lifecycle actions available to an authenticated MCP connection. With an API key, use terminal statuses instead:

Goal	Do this
Remove an initiative	`PATCH` `status: "archived"`
Remove a milestone	`PATCH` `status: "cancelled"`
Remove a run	`POST /api/v1/runs/{runId}/actions/cancel`
Retire an artifact	`PATCH` `status: "superseded"` or `"archived"`
Withdraw a decision	Resolution is human-only; see the decision page
Pause or cancel hierarchy	`POST /api/v1/lifecycle` with `level`, `id`, `action` (pause/resume/retry/cancel)

Lifecycle actions — `POST /api/v1/lifecycle`

One route pauses, resumes, retries, or cancels any node of the hierarchy. It takes exactly three fields, all required:

Field	Type	Meaning
`level`	`initiative` `workstream` `milestone` `task` `run`	Which kind of node.
`id`	UUID	The node’s ID.
`action`	`pause` `resume` `retry` `cancel`	What to do.

Note the field names: this route takes level and id, not entity_type and entity_id (those belong to the artifact and receipt surfaces). There is no status or target-state field — the target state is implied by action, and cascades to child runs.

curl https://useorgx.com/api/v1/lifecycle \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "level": "initiative",
    "id": "2c6d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "action": "pause"
  }'

The response is a bare object — no { data, meta } envelope — returned with 200 when ok is true and 422 when it is false:

{
  "ok": true,
  "action": "pause",
  "level": "initiative",
  "id": "2c6d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
  "affected": { "nodes": 4, "runsPaused": 2, "runsCancelled": 0, "redispatched": 0 },
  "message": "Initiative paused."
}

A refusal adds error and blockReasons to the lifecycle result. Lifecycle errors use the same structured error envelope as the rest of /api/v1.

Where the IDs come from

ID you need	Obtain it from
any entity `id`	`POST /api/entities` response `data.id`, or `GET /api/entities?type=...` listing rows
`workspace_id`	`GET /api/v1/me` → `data.default_workspace_id` or `data.workspaces[].id` (API key)
`initiative_id`	`POST /api/v1/initiatives` response `data.initiativeId`, or `GET /api/entities?type=initiative`
`milestone_id`	`POST /api/v1/initiatives` response `data.milestoneId`, or `GET /api/entities?type=milestone`
`workstream_id`	`POST /api/v1/initiatives` response `data.workstreamId`, or `GET /api/entities?type=workstream`
`owner_id`	Defaults to your API key identity; you rarely need to send it.

MCP equivalents

MCP tool	Relationship to this endpoint
`orgx_search`	Typed searches call `GET /api/entities` with the same parameters.
`orgx_write`	Creates call `POST /api/entities`; updates call `PATCH /api/entities`.
`orgx_inspect`	Reads `GET /api/entities?type=...&id=...` plus MCP execution context.
`orgx_act`	Runs the lifecycle actions available to an authenticated MCP connection.

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

Compatibility entities

Authentication

Methods

Entity type vocabulary

GET — list and fetch

Query parameters

Response envelope

POST — create

PATCH — update

Deletion and terminal states

Lifecycle actions — `POST /api/v1/lifecycle`

Where the IDs come from

MCP equivalents

​Authentication

​Methods

​Entity type vocabulary

​GET — list and fetch

​Query parameters

​Response envelope

​POST — create

​PATCH — update

​Deletion and terminal states

​Lifecycle actions — POST /api/v1/lifecycle

​Where the IDs come from

​MCP equivalents

Authentication

Methods

Entity type vocabulary

GET — list and fetch

Query parameters

Response envelope

POST — create

PATCH — update

Deletion and terminal states

Lifecycle actions — `POST /api/v1/lifecycle`

Where the IDs come from

MCP equivalents