> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/api-and-integrations/rest-api-reference.md).

# REST API Reference

Every capability in the platform is reachable over HTTPS under `/api/v1/` on your deployment domain. The [Python SDK](/api-and-integrations/sdk-getting-started.md) is built entirely on this surface; anything the SDK does, plain HTTP can do.

## Interactive reference

Two references describe the API:

* **Interactive API Reference**: `https://sandbox.rootcause.ai/api/v1/docs` explores every endpoint, shows request and response schemas, and lets you try calls against your data.
* **OpenAPI 3.1 specification**: `https://sandbox.rootcause.ai/api/v1/openapi.json` feeds any code generator to produce a typed client in your language of choice.

Replace `sandbox.rootcause.ai` with your own deployment domain throughout.

## Authentication

Every request carries a Bearer token: either an API key created on the Organisation API page, or an OAuth access token obtained through the platform's OAuth server (authorization code with PKCE, dynamic client registration supported). OAuth tokens are audience-bound: request the resource `https://<your-domain>/api/v1` during authorization and token exchange, or calls will be rejected with an audience mismatch.

Keys carry granular scopes (for example `ontology:read`, `simulations:execute`, `digital-twins:write`); a request with a missing scope answers 403 with the scopes it needed. See [API Access](/api-and-integrations/api-access.md) for scope management.

## Conventions

* **Envelope**: successful responses wrap payloads as `{"data": ...}`. List endpoints add `{"pagination": {"cursor", "hasMore", "total"}}`; pass `cursor` back to fetch the next page.
* **Async work**: operations that run pipelines answer `202` with `{"data": {"jobId", "status", "links"}}` (or `runId` for simulations). Poll `links.self` until the status is terminal (`completed`, `failed`, `cancelled`); simulations expose `links.results` when complete.
* **Errors**: failures are RFC 7807 problem documents (`application/problem+json`) with `type`, `title`, `status`, `detail`.
* **Rate limits**: responses carry rate limit headers; a `429` includes `Retry-After`.
* **Identity**: organisation, workspace, and user identity come from the credential and the URL path, and identity fields in request bodies are ignored. Connectors are the one place a workspace is a *choice* rather than identity: they belong to the organisation and can import into any workspace in it, so `POST /connectors/{id}/import` and `POST /connectors/{id}/direct-query` accept an optional `workspaceId` naming the target. A workspace-scoped credential supplies it and need not send it; an organisation-wide credential has to, and one naming a workspace outside the credential's scope is refused.
* **Webhooks**: every long-running operation accepts an optional `webhookUrl`. When the job or run reaches a terminal state, the platform POSTs a JSON payload (`event`, `jobId`/`runId`, `status`, `workspaceId`, `completedAt`, `error` on failure) to that URL — once, best effort, unsigned, and only to public, non-internal hosts over http or https. Polling stays the source of truth; treat the webhook as a wake-up call, not a delivery guarantee.