> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> The curated, versioned, API-key-authenticated /v1 REST surface.

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`](/dev/sdks/typescript) and the [MCP server](/dev/mcp/overview) are built on. Every endpoint below has an interactive **"Try it"** panel; paste a key and run a real request.

## Base URL

```
https://api.custral.com
```

## Authentication

Almost every `/v1` request authenticates with a **secret API key** (`sk_…`), created in **Settings → Applications** or from the [CLI](/dev/cli/overview):

```bash theme={null}
curl https://api.custral.com/v1/me \
  -H "Authorization: Bearer sk_live_..."
```

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](/dev/auth/overview) for the full model.

The exception is [Applications & keys](/dev/api-reference/applications), which authenticates with a signed-in session instead. A key can't be the thing that creates itself.

<Warning>
  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`](/dev/sdks/browser) (usage) or [`@custral/widget`](/dev/sdks/react) (chat).
</Warning>

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

<CodeGroup>
  ```json Success theme={null}
  {
    "data": { "id": "rec_123", "action": "created", "ignoredFields": [] },
    "reqId": "req_2a1f9c8e7b6d5"
  }
  ```

  ```json Error theme={null}
  {
    "error": { "code": "insufficient_scope" },
    "reqId": "req_2a1f9c8e7b6d5"
  }
  ```
</CodeGroup>

The SDK unwraps this for you, `records.create(...)` returns the `data` payload directly and throws a typed error on `error`. See [Errors](/dev/errors/overview) 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.

<Card title="Webhooks" icon="webhook" href="/dev/webhooks/overview">
  The event catalog, signature verification, and delivery behaviour.
</Card>

## Endpoints

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


## Related topics

- [Applications & API keys](/dev/applications.md)
- [Developer Overview](/dev/overview.md)
- [TypeScript SDK](/dev/sdks/typescript.md)
- [Authentication](/dev/auth/overview.md)
- [Errors](/dev/errors/overview.md)