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

# Overview

> The data-plane API your applications call to run models: OpenAI- and Anthropic-compatible endpoints behind one base URL.

## Base URL

```text Base URL theme={null}
https://inference.pearlresearch.ai/v1
```

Every path below is relative to it. Organizations pinned to a region use that region's base URL instead, see [Data residency](/docs/data-residency.md).

## Authentication

Send an inference API key as a bearer token:

```bash theme={null}
Authorization: Bearer $PEARL_API_KEY
```

* Inference keys start with `sk-prl-infapi-`; create them on the [API Keys](https://platform.pearlresearch.ai/api-keys) page. Management keys (`sk-prl-mgmt-`) cannot call models.
* `/models` also accepts the key in an `x-api-key` header.

## Endpoints

| Endpoint | Description |
| - | - |
| [`POST /chat/completions`](/docs/reference/chat-completions) | OpenAI-compatible chat, with streaming, tools, JSON mode, and reasoning. |
| [`POST /responses`](/docs/reference/responses) | Stateless OpenAI Responses. |
| [`POST /messages`](/docs/reference/messages) | Anthropic Messages. |
| [`POST /messages/count_tokens`](/docs/reference/messages/count-tokens) | Count a Messages request's input tokens without generating. |
| [`POST /completions`](/docs/reference/completions) | Legacy raw-prompt completions. |
| [`GET /models`](/docs/reference/models) | The live model catalog, with limits and capabilities per model. |

## Requests

* Bodies are JSON objects, up to 20 MiB. They may be compressed with gzip, br, zstd, or deflate (set `Content-Encoding`).
* Every response carries an `X-Request-ID` header. Send your own UUID in `X-Request-ID` to use it as the ID. Include the ID when you contact support.
* Streaming responses are server-sent events. An error after the stream starts arrives as an event in the stream, not as an HTTP status, see [Streaming](/docs/streaming.md).

## Errors

Errors are JSON in OpenAI's shape, with the request ID in the body. `type` is one of `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error`, or `api_error`, and `code` is present only when set.

```json theme={null}
{
  "error": {
    "message": "unknown model",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "request_id": "6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87"
  }
}
```

## Status codes

| Status | Meaning |
| - | - |
| `400` | Invalid request: malformed JSON, a missing or wrongly typed field, or an unsupported parameter. Fix it; retrying unchanged fails again. |
| `401` | Missing, unknown, revoked, or expired API key, a key over its credit limit, or a management key. |
| `402` | Your organization is out of credits. Top up on the [Billing](https://platform.pearlresearch.ai/billing) page, then retry. |
| `403` | Wrong endpoint for your organization's [inference region](/docs/data-residency.md). |
| `404` | Unknown model (code `model_not_found`) or path. |
| `408` | The request body took longer than 30 seconds to arrive. |
| `413` | Request body over 20 MiB. |
| `415` | Unsupported Content-Encoding (gzip, br, zstd, and deflate are accepted). |
| `429` | A [rate limit](/docs/plans.md) for your organization and the model was reached. Wait for the `Retry-After` header's seconds. |
| `500` | Internal error. Safe to retry with backoff. |
| `502` | The model server failed or returned a malformed response. Retry with backoff. |
| `503` | Temporarily unavailable, for example during a deploy. Retry after the `Retry-After` header's seconds. |
| `504` | The model server timed out. Retry with backoff. |
| `529` | No capacity for the model right now (code `no_capacity`). Retry with backoff. |

> [!NOTE]
>
> Retry `429` and `5xx` with exponential backoff and jitter, honoring `Retry-After` when present. A `400`, `401`, `402`, `403`, or `404` fails the same way until the request, key, balance, or endpoint changes.

## Rate limits

Limits apply per organization and model: requests, input tokens, and output tokens per minute, and concurrent requests. Your plan sets them, see [Plans & rate limits](/docs/plans.md). Over a limit, a request gets `429` with a `Retry-After` header in seconds.

## Anthropic-compatible endpoints

* `/messages` and `/messages/count_tokens` accept the key in an `x-api-key` header, as the Anthropic SDK sends it, or as a bearer token. If you send both headers, they must carry the same key.
* They require an `anthropic-version` header (any single value, for example `2023-06-01`) and `Content-Type: application/json`.
* Their errors use Anthropic's shape, and their responses also carry the ID in a `request-id` header:

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "unknown model"
  },
  "request_id": "6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.