Skip to main content
The Custral API is a REST API over HTTPS. The /v1 namespace is the curated, versioned, public surface: the same endpoints the official @custral/sdk and the MCP server are built on. Every endpoint below has an interactive “Try it” panel; paste a key and run a real request.

​
Base URL

​
Authentication

Almost every /v1 request authenticates with a secret API key (sk_…), created in Settings → Applications or from the CLI:
The X-Api-Key: sk_… header is also accepted. Each endpoint requires a specific scope (e.g. records:read) that you grant the key. See Authentication for the full model. The exception is Applications & keys, which authenticates with a signed-in session instead. A key can’t be the thing that creates itself.
A secret key can read and write your workspace data. Keep it server-side, never ship sk_… to a browser. For browser use, use a publishable key with @custral/js (usage) or @custral/widget (chat).

​
Response envelope

Every response is wrapped in a small envelope. Success carries a data payload; failure carries an error.code. Both include the request id (reqId).
The SDK unwraps this for you, records.create(...) returns the data payload directly and throws a typed error on error. See Errors for the full code catalog.

​
Rate limits

Responses carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. A 429 (code: rate_limited) means you’ve exceeded the budget, honour Retry-After / RateLimit-Reset before retrying.

​
Events and webhooks

The endpoints below are how you ask Custral for something. To be told when a workspace changes, register a webhook: Custral posts a signed payload to your endpoint when a record, form, task or conversation event fires.

Webhooks

The event catalog, signature verification, and delivery behaviour.

​
Endpoints

Pick an endpoint from the sidebar to see its parameters, scopes, schemas, and a live playground.