REST API Reference

Every capability in the platform is reachable over HTTPS under /api/v1/ on your deployment domain. The Python SDK is built entirely on this surface; anything the SDK does, plain HTTP can do.

Interactive reference

Two living resources are generated from the running server and are always in sync with it:

• 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 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 always come from the credential and the URL path. Identity fields in request bodies are ignored.

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