updateBudget.md
Update a token budget
OpenAPI
yaml
openapi: 3.1.0 info: title: Barndoor LLM Gateway API version: 1.0.0 description: > REST API for the Barndoor LLM Gateway: configure providers, model routes, pricing, governance, and operate a multi-provider LLM platform programmatically.
All endpoints in this document are scoped to your organization. They are the
same APIs powering the Barndoor portal under **LLM Configuration**,
**LLM Controls**, and **Settings - My Models**, exposed for teams that
prefer scripting over the UI.
## Base URL
All requests are issued against your Barndoor instance:
https://app.barndoor.ai/api/llm-gateway
Replace `app.barndoor.ai` with your tenant host if you run on Enterprise.
## Authentication
Endpoints accept a JWT Bearer token issued by your Barndoor identity
provider. Tokens can be obtained interactively via the Barndoor SDK:
```ts
const sdk = await loginInteractive();
```
The token must be sent in the `Authorization` header on every request:
Authorization: Bearer eyJhbGciOi...
Note: the `bd-...` API keys you create through these endpoints are for
runtime LLM traffic (`/v1/chat/completions`, `/v1/messages`, etc.), not for
administrative calls. Administrative endpoints require a user/admin JWT.
## Permissions
Most endpoints require an `admin` (or higher) role on the calling user.
Read-only endpoints are typically accessible by all authenticated users.
Read-only listings under `/user/...` are scoped to the authenticated user.
## Errors
Errors are returned as JSON with a stable shape:
```json
{ "error": "BadRequest", "message": "request_timeout_secs must be between 1
and 3600" }
```
contact: name: Barndoor Support url: https://barndoor.ai servers:
- url: https://{host}/api/llm-gateway description: >- Production / Trial (Barndoor SaaS). The gateway lives on your Barndoor control-plane host. For Enterprise or self-hosted deployments, replace the host with your portal hostname — the authoritative value is shown on Settings → My Models in the portal. variables: host: description: Your Barndoor control-plane (portal) hostname default: app.barndoor.ai
- url: https://app.barndooruat.com/api/llm-gateway description: UAT
- url: https://app.barndoordev.com/api/llm-gateway description: Dev security:
- BearerAuth: [] tags:
- name: Credentials description: >- Reusable upstream credentials (API keys, AWS roles, Vertex service accounts)
- name: Providers description: Named upstream providers backed by credentials and a model family
- name: Provider Catalog description: Read-only catalog of supported upstream provider templates
- name: Model Routes description: Map client-facing aliases to one or more upstream provider/model pairs
- name: Model Pricing description: Per-million-token input/output costs for usage and budget reporting
- name: Rate Limits description: Requests-per-minute and tokens-per-minute caps
- name: Token Budgets description: Daily, weekly, or monthly token and cost ceilings
- name: Model Access description: Allowlist or denylist policies for models, providers, or aliases
- name: Smart Models description: Routing policies that pick a target model based on the request
- name: Governance Configuration description: Org-wide behavior toggles for the LLM Gateway
- name: Route Health description: Operational view of upstream route ejection and recovery
- name: API Keys
description: Org-managed gateway API keys (the
bd-...keys callers send on/v1/...) - name: User
description: Self-service endpoints for the authenticated user
paths:
/admin/budgets/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
put:
tags:
- Token Budgets summary: Update a token budget operationId: updateTokenBudget requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateTokenBudgetRequest'
responses: '200': description: The updated budget content: application/json: schema: $ref: '#/components/schemas/TokenBudget' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound'
- name: id
in: path
required: true
schema:
type: string
format: uuid
put:
tags:
components:
schemas:
UpdateTokenBudgetRequest:
type: object
description: All fields optional; sent fields replace the existing value.
properties:
name:
type: string
token_limit:
type: integer
format: int64
alert_thresholds:
type: array
items:
type: integer
enabled:
type: boolean
cost_limit:
type: number
nullable: true
period:
$ref: '#/components/schemas/BudgetPeriod'
action_on_exhaust:
$ref: '#/components/schemas/BudgetActionOnExhaust'
traffic_type:
$ref: '#/components/schemas/TrafficType'
TokenBudget:
type: object
required:
- id
- org_id
- name
- scope_type
- period
- token_limit
- alert_thresholds
- action_on_exhaust
- traffic_type
- currency
- enabled
properties:
id:
type: string
format: uuid
org_id:
type: string
format: uuid
name:
type: string
example: Engineering monthly tokens
scope_type:
$ref: '#/components/schemas/RateLimitScope'
scope_id:
type: string
format: uuid
nullable: true
scope_value:
type: string
nullable: true
period:
$ref: '#/components/schemas/BudgetPeriod'
token_limit:
type: integer
format: int64
example: 50000000
alert_thresholds:
type: array
items:
type: integer
minimum: 0
maximum: 100
example:
- 80
- 90
action_on_exhaust:
$ref: '#/components/schemas/BudgetActionOnExhaust'
traffic_type:
$ref: '#/components/schemas/TrafficType'
cost_limit:
type: number
nullable: true
description: Optional spend ceiling in currency
currency:
type: string
default: USD
target_provider_id:
type: string
format: uuid
nullable: true
description: Restrict to traffic served by a specific provider
target_upstream_model:
type: string
nullable: true
description: Restrict to traffic that ends up at this upstream model
target_model_alias:
type: string
nullable: true
description: Restrict to requests that used this client-facing alias
enabled:
type: boolean
BudgetPeriod:
type: string
enum:
- daily
- weekly
- monthly
- quarterly
- yearly
BudgetActionOnExhaust:
type: string
enum:
- block
- alert
description: |
- block — refuse new requests until the next period
- alert — emit alerts at the configured thresholds but keep serving
TrafficType:
type: string
description: Whether the policy applies to LLM, MCP, or both kinds of traffic
enum:
- all
- llm
- mcp
default: all
RateLimitScope:
type: string
description: Who the rate limit applies to
enum:
- org
- team
- user
- role
- group
- api_key
- mcp_server
- agent
- project
- llm_provider
- model
- model_alias
Error:
type: object
required:
- error
- message
properties:
error:
type: string
description: A short machine-readable error code
example: BadRequest
message:
type: string
description: A human-readable description of what went wrong
example: request_timeout_secs must be between 1 and 3600
responses:
BadRequest:
description: The request body or query parameters were invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The resource does not exist or is not accessible by this organization
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: |
JWT obtained through Barndoor's authentication flow. Pass the token
verbatim in Authorization: Bearer <token>. Use the Barndoor SDK's
loginInteractive() helper to obtain a token in scripts and notebooks.