API overview

Start with work and receipts, then add organization, processes, events, and projections as your integration grows.

The published REST API uses one base URL:

https://useorgx.com/api/v1

The unversioned Entities route is a compatibility adapter for older workspace and MCP integrations. It is not part of the published v1 contract and is not a starting point for new integrations. Use the dedicated /api/v1 resources and the OpenAPI document instead.

curl https://useorgx.com/api/v1/work \
  -X POST \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: launch-plan-review-001' \
  -d '{"title":"Review the launch plan"}'

Learn the API in this order

Stage	What you can do	Start here
1. Work	Create visible work and complete it with evidence	POST /work
2. Organize	Create initiatives and place work deliberately	POST /initiatives
3. Coordinate	Model processes and transfer responsibility	/operating-processes, /handoffs
4. Synchronize	Consume accepted changes in cursor order	GET /events/stream
5. Analyze	Read Work Ledger, adoption, value, and usage views	GET /projections/*

Receipts are the front door for proof. Validate a portable receipt without an account, or import one into a workspace with the same API key used by other workspace operations.

To understand the resources themselves — their fields, lifecycles, every operation on each, and where every referenced ID comes from — start with the entity map.

Shared guarantees

Topic	Contract
Authentication	One oxk_ API key works across published workspace operations.
Errors	JSON errors use { "error": { "code", "message", ... } }.
Mutations	Send Idempotency-Key; the same key and input return the original result.
Event pages	Continue with the opaque nextCursor; deduplicate by event ID.
Version	/api/v1 is the public REST version.

Success responses are not one shape

Errors share one envelope. Successes do not. Three families are in production, and the endpoint pages state which one each operation returns. Read the shape from the endpoint page rather than assuming:

Family	Shape	Endpoints
Envelope	{ "data": ..., "meta": { ... } }	/work, /work/{id}/complete, /initiatives, /events/stream, /episodes, /handoffs, /operating-processes, /discovery-runs, /projections/*
Named collection / bare object	{ "decision": ... }, { "decisions": [ ... ] }, { "artifacts": [ ... ] }, { "run", "receipt", "steps", "blocker" }	/decisions, /artifacts (GET), /runs/{runId}, /operating-processes/{processId} (GET)
ok-flagged	{ "ok": true, ... }	/agent-work-receipts, /artifacts/by-entity

POST /api/v1/lifecycle returns its successful result bare. Its errors use the shared envelope like every other versioned operation.

Pagination on /api/v1 uses meta.nextCursor and meta.hasMore. Compatibility entities reads use their legacy pagination fields; new clients should use the resource-specific v1 operation documented in OpenAPI.

These differences are real behavior, not documentation shorthand. Write clients against the shape the endpoint page names. The endpoint page and the OpenAPI document are authoritative for that operation’s success shape.

Account-free utilities need no key. Inbound provider callbacks are documented separately on the webhooks page.

Other integration surface

Use the hosted MCP endpoint when an AI client needs tools, resources, and browser-based OAuth. MCP and REST share workspace authority but serve different client protocols.

The OpenAPI document is the machine contract. If an operation is absent from it, treat that operation as unsupported.