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

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

```text theme={"dark"}
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](https://useorgx.com/api/v1/openapi.yaml) instead.

```bash theme={"dark"}
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`](/docs/api/quickstart)     |
| 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](/docs/api/entities/overview).

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

<Info>
  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.
</Info>

Account-free utilities need no key. Inbound provider callbacks are documented
separately on the [webhooks](/docs/api/webhooks) page.

## Other integration surface

Use the [hosted MCP endpoint](/docs/api/mcp-protocol) 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](https://useorgx.com/api/v1/openapi.yaml) is the machine
contract. If an operation is absent from it, treat that operation as unsupported.