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

# API reference

> Base URL, authentication, content types, the response envelope, and error format for the PRYSM REST API.

The PRYSM API is **OpenAI-compatible** and speaks JSON over HTTPS. If you've used the
OpenAI API, you already know it — the only differences are an enriched response
(`model: "auto"` and a `prysm` block) and a few PRYSM-specific endpoints.

## Base URL

```
https://api.prysm1.com/v1
```

All endpoints below are relative to this base. It already includes the `/v1` version
segment.

## Authentication

Every authenticated request carries your secret key as a bearer token. See
[Authentication](/authentication) for details and environment variables.

```bash theme={null}
Authorization: Bearer prysm_sk_your_key
```

| Endpoint                                                      | Method | Auth     |
| ------------------------------------------------------------- | ------ | -------- |
| [`/chat/completions`](/api-reference/chat-completions)        | POST   | Required |
| [`/v2/orchestrate`](/api-reference/orchestrate)               | POST   | Required |
| [`/v2/code`](/api-reference/code)                             | POST   | Required |
| [`/v2/compliance/preview`](/api-reference/compliance-preview) | POST   | Required |
| [`/route`](/api-reference/route)                              | POST   | Required |
| [`/usage`](/api-reference/usage)                              | GET    | Required |
| [`/models`](/api-reference/models)                            | GET    | None     |
| [`/brain/validate`](/api-reference/brain-validate)            | POST   | None     |
| [`/proof/{request_id}`](/api-reference/proof)                 | GET    | None     |
| [`/health`](/api-reference/health)                            | GET    | None     |

## Content type

Send `Content-Type: application/json` with request bodies. Responses are always JSON.

## The response envelope

`/chat/completions` returns a standard OpenAI completion **plus** a top-level `prysm`
block describing the routing decision, cost, latency, and a
[PrysmProof](/concepts/prysmproof). OpenAI-compatible clients ignore the extra field; the
[SDKs](/sdks/python) expose it via `extension()`.

```json theme={null}
{
  "id": "prysm-a1b2c3d4",
  "object": "chat.completion",
  "model": "deepseek-v4-flash",
  "choices": [ ... ],
  "usage": { ... },
  "prysm": { "routing": { ... }, "cost": { ... }, "proof": { ... } }
}
```

## Errors

PRYSM uses conventional HTTP status codes. Error bodies wrap a `detail` object with a
machine-readable `error` code and a human `message`:

```json theme={null}
{
  "detail": {
    "error": "invalid_api_key",
    "message": "Invalid or missing PRYSM API key."
  }
}
```

| Status | Error code              | Meaning                                          |
| ------ | ----------------------- | ------------------------------------------------ |
| `401`  | `invalid_api_key`       | The key is missing, malformed, or revoked.       |
| `404`  | `proof_not_found`       | No record matches the given request ID.          |
| `429`  | `rate_limit_exceeded`   | You've exceeded your plan's per-minute limit.    |
| `502`  | `provider_error`        | An upstream provider returned an error.          |
| `503`  | `no_provider_available` | No provider API keys are configured server-side. |

<Note>
  The SDKs raise these as clean exceptions/errors rather than returning raw payloads, so
  you can `try/catch` around any call.
</Note>

## Versioning & compatibility

PRYSM preserves OpenAI request and response shapes. Unknown fields you send are tolerated,
and the PRYSM-specific additions (`routing_mode`, `brain_config`, and the `prysm` response
block) are designed to be ignored safely by standard OpenAI clients.