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

# 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

<CardGroup cols={2}>
  <Card title="Credentials" icon="key" href="/api-reference/llm-gateway/credentials/listCredentials">
    Reusable upstream credentials — API keys, AWS roles, Vertex service accounts.
  </Card>

  <Card title="Providers" icon="server" href="/api-reference/llm-gateway/providers/listProviders">
    Named upstream providers backed by a credential and a model family.
  </Card>

  <Card title="Model Routes" icon="route" href="/api-reference/llm-gateway/model-routes/listAllRoutes">
    Map a client-facing alias to one or more provider/model pairs with failover.
  </Card>

  <Card title="Model Pricing" icon="coins" href="/api-reference/llm-gateway/model-pricing/listPricing">
    Per-million-token costs and history; powers usage and budget reporting.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api-reference/llm-gateway/rate-limits/listRateLimits">
    Requests-per-minute and tokens-per-minute caps.
  </Card>

  <Card title="Token Budgets" icon="wallet" href="/api-reference/llm-gateway/token-budgets/listBudgets">
    Daily, weekly, and monthly token / cost budgets with alert thresholds.
  </Card>

  <Card title="Model Access" icon="shield" href="/api-reference/llm-gateway/model-access/listModelAccess">
    Allow- and deny-list policies for models, providers, or aliases.
  </Card>

  <Card title="Smart Models" icon="sparkles" href="/api-reference/llm-gateway/smart-models/listSmartModels">
    Routing policies that pick a target model per-request.
  </Card>

  <Card title="Governance Configuration" icon="sliders" href="/api-reference/llm-gateway/governance/getGovernanceConfig">
    Org-wide gateway behavior toggles.
  </Card>

  <Card title="Route Health" icon="heart-pulse" href="/api-reference/llm-gateway/route-health/getRouteHealth">
    Operational view of upstream ejection and recovery.
  </Card>

  <Card title="API Keys" icon="lock" href="/api-reference/llm-gateway/api-keys/listApiKeys">
    Org-managed `bd-…` gateway API keys.
  </Card>

  <Card title="User self-service" icon="user" href="/api-reference/llm-gateway/user/listUserApiKeys">
    Personal API keys and the model catalog scoped to the calling user.
  </Card>
</CardGroup>

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