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

> Public Preview reference for the OrgX MCP API, REST API, and webhooks.

OrgX is API-first infrastructure for AI-native teams. The API gives clients,
agents, and internal systems governed access to workspace context, initiatives,
decisions, artifacts, memory, and agent execution state.

<Info>
  The OrgX REST API is in **Public Preview**. Endpoints, authentication,
  errors, pagination, idempotency, and webhook conventions are documented
  publicly so integrations can be built and reviewed before General
  Availability.
</Info>

## API Surfaces

| Surface  | Endpoint                         | Best for                                                        | Status         |
| -------- | -------------------------------- | --------------------------------------------------------------- | -------------- |
| MCP API  | `https://mcp.useorgx.com/mcp`    | AI clients, agent tools, widgets, approval flows                | Public Preview |
| REST API | `https://useorgx.com/api/client` | System integrations, local clients, dashboards, runtime bridges | Public Preview |
| Webhooks | Customer-provided HTTPS endpoint | Event delivery to external systems                              | Public Preview |

## At a Glance

| Topic           | Contract                                                                                                                                                          |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication  | REST uses user-scoped API keys in `Authorization: Bearer oxk_...`. MCP uses OAuth 2.1 with PKCE.                                                                  |
| Data scope      | Every request is scoped to the authenticated user and workspace.                                                                                                  |
| Request format  | JSON request bodies with `Content-Type: application/json`.                                                                                                        |
| Response format | JSON. Most preview REST endpoints return either `{ "ok": true, "data": ... }` or a resource-specific JSON object.                                                 |
| Versioning      | Public Preview uses the current stable preview contract. `OrgX-Version` is reserved for integrations that pin a contract date as versioned compatibility hardens. |
| Idempotency     | Use client-generated idempotency keys where an endpoint documents support. Cross-endpoint retry semantics are being standardized during Public Preview.           |
| Pagination      | List endpoints use `limit`, `offset`, `total`, and `pagination.has_more` where available.                                                                         |
| Rate limits     | Preview limits are conservative: reads are higher than writes, and agent dispatch has tighter limits.                                                             |
| Sandbox         | Use a sandbox workspace and test API key for reviewer, CI, and demo integrations.                                                                                 |

## First REST Call

Use the bootstrap endpoint to prove authentication, workspace resolution, and
integration readiness:

```bash theme={"dark"}
curl https://useorgx.com/api/client/bootstrap \
  -H "Authorization: Bearer $ORGX_API_KEY" \
  -H "Accept: application/json"
```

Successful responses include the workspace, project context, available
capabilities, and any setup gaps the client should handle before dispatching
work.

```json theme={"dark"}
{
  "ok": true,
  "data": {
    "workspace": {
      "id": "d85d7e6f-58f2-4637-b3a0-3cf2c3b8a638",
      "name": "Acme"
    },
    "sourceClient": "custom",
    "capabilities": [],
    "setup": {
      "ready": true
    }
  }
}
```

## First MCP Calls

For AI clients, start with MCP. These calls orient the model before it reads or
writes work:

```text theme={"dark"}
workspace action=get -> orgx_recommend -> orgx_search(type=decision,status=pending)
```

1. `workspace action=get` confirms the active workspace and auth context.
2. `orgx_recommend` returns initiatives, agents, and recent activity.
3. `orgx_search` with `type=decision,status=pending` shows work awaiting review.

## Public Preview Resource Map

| Resource    | REST                                                               | MCP                                         | Notes                                                         |
| ----------- | ------------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------- |
| Workspaces  | [`/api/client/bootstrap`](/docs/api/rest/workspaces)                    | `workspace`                                 | Resolve current workspace and client setup state.             |
| Initiatives | [`/api/client/live/initiatives`](/docs/api/rest/initiatives)            | `orgx_search`, `orgx_recommend`             | Read portfolio state and progress.                            |
| Decisions   | [`MCP-first`](/docs/api/rest/decisions)                                 | `orgx_decide`, `orgx_decide`, `orgx_decide` | REST decision resources are graduating during Public Preview. |
| Agents      | [`/api/client/live/agents`, `/api/client/spawn`](/docs/api/rest/agents) | `orgx_spawn`, `orgx_spawn`                  | Read status and preflight agent dispatch.                     |
| Artifacts   | [`/api/client/artifacts`](/docs/api/rest/artifacts)                     | artifact resources and approval tools       | Register artifacts and fetch entity-linked outputs.           |
| Memory      | [`/api/client/tools/execute`](/docs/api/rest/memory)                    | `orgx_search`, `orgx_search`                | Search org context through governed tools.                    |
| Webhooks    | [`Webhooks`](/docs/api/webhooks)                                        | N/A                                         | Event delivery for external systems.                          |

## Authentication Choices

<CardGroup cols={2}>
  <Card title="REST API keys" icon="key" href="/docs/api/authentication">
    Generate a user-scoped `oxk_...` API key in OrgX settings and send it as a
    bearer token to `/api/client/*`.
  </Card>

  <Card title="MCP OAuth" icon="lock" href="/docs/api/mcp-protocol">
    Connect ChatGPT, Claude, Cursor, VS Code, or another MCP client through
    OAuth 2.1 with PKCE.
  </Card>
</CardGroup>

## Status and Compatibility

Public Preview means:

* The docs are public and reviewable.
* Preview endpoints are intended for real integrations.
* Breaking changes are still possible before GA, but they will be documented.
* Production workspace data always requires authentication.
* Customer data is never available through anonymous API calls.

For a Stripe-style review, this is the canonical documentation URL:

```text theme={"dark"}
https://docs.useorgx.com/docs/api/overview
```