introduction.md

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.

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

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:

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:

curl https://app.barndoor.ai/api/llm-gateway/admin/providers \
  -H "Authorization: Bearer eyJhbGciOi..."
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.

Permissions

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

Conventions

Errors

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

{
  "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