# LLM Gateway API

Programmatically configure and operate the Barndoor LLM Gateway: providers, model routes, pricing, governance, and gateway API keys.

The LLM Gateway API is the same surface that powers the **LLM Management** hub (including its **Controls** sections) and **Settings → My Models** in the Barndoor portal — exposed so platform teams can script provisioning, run automated audits, and integrate with their own management tooling.

<Note>
  These endpoints control how the gateway routes traffic. They are **distinct** from the runtime LLM endpoints (`/v1/chat/completions`, `/v1/messages`, `/v1/embeddings`, …) — those are documented in [Quickstart Guide](/how-tos/llm-gateway-quickstart#sending-requests).
</Note>

## Base URL

All requests are issued against your Barndoor instance. The administrative API sits under `/api/llm-gateway`:

```
https://app.barndoor.ai/api/llm-gateway
```

Replace `app.barndoor.ai` with your tenant host on Enterprise.

## Authentication

Endpoints require a **JWT Bearer token** issued by your organization's identity provider — the same login flow you use for the Barndoor portal. The easiest way to obtain a token from a script is the Barndoor SDK:

```ts theme={null}
import { loginInteractive } from "@barndoor/sdk";

const sdk = await loginInteractive();
// sdk includes the bearer token; pass it on every API call.
```

Send the token on every request:

```bash theme={null}
curl https://app.barndoor.ai/api/llm-gateway/admin/providers \
  -H "Authorization: Bearer eyJhbGciOi..."
```

<Warning>
  The `bd-…` API keys you create through these endpoints are for the runtime proxy (`/v1/chat/completions`, `/v1/messages`, etc.) — they are **not** accepted on `/admin/...` or `/user/...` paths. Use a JWT for administration and a `bd-…` key for traffic.
</Warning>

## Permissions

| Endpoint family | Required role                                        |
| --------------- | ---------------------------------------------------- |
| `/admin/...`    | `admin` (or higher) on the calling user              |
| `/user/...`     | Any authenticated user (results scoped to that user) |

## Conventions

* Every resource is automatically scoped to the caller's organization. There is no `org_id` parameter on any endpoint — it's resolved from your JWT.
* All timestamps are RFC 3339 (`2026-06-12T18:30:00Z`).
* All identifiers are UUIDv4.
* `PUT` / update endpoints accept partial bodies — fields you omit are left unchanged. A handful of endpoints also distinguish **omitted** from **explicit `null`** on `Option`-typed columns; the affected fields are documented inline.

## Errors

Errors come back with a stable JSON shape and an HTTP status code that matches the failure mode:

```json theme={null}
{
  "error": "BadRequest",
  "message": "request_timeout_secs must be between 1 and 3600"
}
```

| Status | Meaning                                                      |
| ------ | ------------------------------------------------------------ |
| `400`  | Validation failure — fix the request body and retry          |
| `401`  | Missing or invalid JWT                                       |
| `403`  | The caller's role does not allow this action                 |
| `404`  | Resource does not exist (or belongs to another organization) |
| `409`  | Conflicts with existing data (rare; specifics in `message`)  |
| `5xx`  | Transient gateway error                                      |

## Resource map

| Title                                   | Description                                                                                       |
| --------------------------------------- | --------------------------------------------------------------------------------- |
| Credentials                             | Reusable upstream credentials — API keys, AWS roles, Vertex service accounts.            |
| Providers                               | Named upstream providers backed by a credential and a model family.                       |
| Model Routes                            | Map a client-facing alias to one or more provider/model pairs with failover.      |
| Model Pricing                           | Per-million-token costs and history; powers usage and budget reporting.                      |
| Rate Limits                             | Requests-per-minute and tokens-per-minute caps.                                               |
| Token Budgets                           | Daily, weekly, and monthly token / cost budgets with alert thresholds.                       |
| Model Access                            | Allow- and deny-list policies for models, providers, or aliases.                            |
| Smart Models                            | Routing policies that pick a target model per-request.                                      |
| Governance Configuration                 | Org-wide gateway behavior toggles.                                                           |
| Route Health                            | Operational view of upstream ejection and recovery.                                           |
| API Keys                                | Org-managed `bd-…` gateway API keys.                                                          |
| User self-service                       | Personal API keys and the model catalog scoped to the calling user.                         |

## Where to next

* New to the gateway? Read [Using the LLM Gateway](/how-tos/use-llm-gateway).
* Looking for the runtime proxy reference (chat completions, messages, embeddings)? See the [Quickstart Guide](/how-tos/llm-gateway-quickstart).