Skip to main content
The LLM Gateway API is the same surface that powers LLM Configuration, LLM Controls, 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.

​
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 familyRequired 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: 
{
  "error": "BadRequest",
  "message": "request_timeout_secs must be between 1 and 3600"
}
StatusMeaning
400Validation failure — fix the request body and retry
401Missing or invalid JWT
403The caller’s role does not allow this action
404Resource does not exist (or belongs to another organization)
409Conflicts with existing data (rare; specifics in message)
5xxTransient gateway error

​
Resource map

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