> ## Documentation Index > Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update relay > Replaces the relay's configuration. The body is the whole relay, not a patch. `name` may be omitted or must equal the path name - a relay cannot be renamed. A secret sent back in its redacted form keeps the stored value, so a client that only ever sees redacted values can save an edit without holding the credential; an `env.` or `vault.` reference is a real change. The new configuration goes live before it is stored; if the save fails the previous configuration is restored. Requires the config store; returns 503 when it is disabled. **Required Permissions** | Permission | Granted via | | - | - | | `Relays:Update` | RBAC role or API key scope | [How permissions work](https://docs.getbifrost.ai/api/procuring-api-keys.md#required-permissions) ## OpenAPI ````yaml /openapi/openapi.json put /api/relays/{name} openapi: 3.1.0 info: title: Bifrost API description: > Bifrost HTTP Transport API for AI model inference and gateway management. This API provides a unified interface for interacting with multiple AI providers including OpenAI, Anthropic, Bedrock, Gemini, and more through a single API, along with comprehensive management APIs for configuring and monitoring the gateway. ## API Structure ### Unified Inference API (`/v1/*`) The primary API using Bifrost's unified format. Model parameters use the format `provider/model` (e.g., `openai/gpt-4`, `anthropic/claude-3-opus`). ### Async Inference API (`/v1/async/*`) Submit inference requests for asynchronous execution. Returns a job ID immediately and allows polling for results. Supports all inference types except batches, files, and containers. ### Provider Integration APIs Native provider-format APIs for drop-in compatibility: - `/openai/*` - OpenAI-compatible API - `/anthropic/*` - Anthropic-compatible API - `/genai/*` - Google GenAI (Gemini) compatible API - `/bedrock/*` - AWS Bedrock compatible API - `/cohere/*` - Cohere compatible API ### Framework Integration APIs Multi-provider proxy endpoints for AI frameworks: - `/litellm/*` - LiteLLM proxy with all provider formats - `/langchain/*` - LangChain compatible endpoints - `/pydanticai/*` - PydanticAI compatible endpoints ### Management APIs (`/api/*`) APIs for managing and monitoring the Bifrost gateway: - `/api/config` - Configuration management - `/api/providers` - Provider and API key management - `/api/plugins` - Plugin management - `/api/governance/*` - Virtual keys, teams, customers, budgets, rate limits, routing rules, and pricing overrides - `/api/logs` - Log search and analytics - `/api/mcp/*` - MCP (Model Context Protocol) client management - `/api/session/*` - Authentication and session management - `/api/cache/*` - Cache management - `/health` - Health check endpoint ## Fallbacks Requests can include fallback models that will be tried if the primary model fails. version: 1.0.0 contact: name: Contact Us url: https://getmaxim.ai/bifrost license: name: Apache 2.0 url: https://opensource.org/licenses/Apache-2.0 servers: - url: '{baseUrl}' description: Your Bifrost instance variables: baseUrl: default: http://localhost:8080 description: Base URL of your Bifrost instance (e.g. https://bifrost.mycompany.com) security: - BearerAuth: [] - BasicAuth: [] - ApiKeyAuth: [] tags: - name: Agent Gateway description: >- Agent registrations, A2A protocol calls, push callbacks, and operation history - name: Models description: Model listing and information - name: Chat Completions description: Chat-based text generation - name: Text Completions description: Text completion generation - name: Responses description: OpenAI Responses API compatible endpoints - name: OCR description: Optical character recognition for documents and images - name: Rerank description: Document reranking by relevance to a query - name: Decisions description: Structured decisions evaluated against annotated function-tool definitions - name: Embeddings description: Text embedding generation - name: Images description: Image generations, editing, and variations - name: Videos description: Video generation and management - name: Audio description: Speech synthesis and transcription - name: Count Tokens description: Token counting utilities - name: Batch description: Batch processing operations - name: Files description: File management operations - name: Containers description: Container management operations - name: Async Jobs description: Asynchronous job submission and retrieval endpoints - name: Realtime description: Realtime WebSocket and WebRTC endpoints - name: OpenAI Integration description: OpenAI-compatible API endpoints (/openai/*) - name: Azure Integration description: Azure OpenAI integration endpoints - name: Anthropic Integration description: Anthropic-compatible API endpoints (/anthropic/*) - name: GenAI Integration description: Google GenAI (Gemini) compatible API endpoints (/genai/*) - name: Bedrock Integration description: AWS Bedrock compatible API endpoints (/bedrock/*) - name: Cohere Integration description: Cohere compatible API endpoints (/cohere/*) - name: Typesafe Integration description: Typesafe compatible API endpoints (/typesafe/*) - name: LiteLLM Integration description: LiteLLM proxy endpoints with multi-provider support (/litellm/*) - name: LangChain Integration description: LangChain compatible endpoints with multi-provider support (/langchain/*) - name: PydanticAI Integration description: >- PydanticAI compatible endpoints with multi-provider support (/pydanticai/*) - name: Health description: Health check endpoints - name: Configuration description: Configuration management endpoints - name: Session description: Session and authentication endpoints - name: Providers description: Provider management endpoints - name: Plugins description: Plugin management endpoints - name: MCP description: Model Context Protocol endpoints - name: Governance description: Virtual keys, teams, and customers management - name: Routing description: Routing rules and complexity analyzer configuration - name: Logging description: Log search and management endpoints - name: Cache description: Cache management endpoints - name: Vault description: Vault secret management endpoints - name: Skills description: Skills Repository management, marketplace, and download endpoints - name: Audit Logs description: >- CADF-compliant audit log search, export, and signature verification endpoints - name: Webhooks description: Webhook endpoint management and signed async-job delivery history - name: Notifications description: >- Role-targeted dashboard notifications, delivered over the dashboard WebSocket - name: News Feeds description: >- RSS and Atom news sources shown in the News tab of the dashboard notification tray - name: Background Jobs description: >- Status, progress and cancellation of durable background jobs (cost recalculation, Warp log indexing, and others) - name: Warp description: >- Configuration for Warp, the dashboard agent that answers questions about the deployment's own telemetry - name: Relays description: >- Relays to non-LLM HTTP APIs - endpoint management, usage preview, Relay Logs and the /relay data plane paths: /api/relays/{name}: put: tags: - Relays summary: Update relay description: > Replaces the relay's configuration. The body is the whole relay, not a patch. `name` may be omitted or must equal the path name - a relay cannot be renamed. A secret sent back in its redacted form keeps the stored value, so a client that only ever sees redacted values can save an edit without holding the credential; an `env.` or `vault.` reference is a real change. The new configuration goes live before it is stored; if the save fails the previous configuration is restored. Requires the config store; returns 503 when it is disabled. operationId: updateRelay parameters: - name: name in: path required: true description: Relay name schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RelayConfig' responses: '200': description: Relay updated content: application/json: schema: $ref: '#/components/schemas/Relay' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/BifrostError' '401': description: Unauthorized — missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/BifrostError' '403': description: Forbidden — authenticated, but not permitted to perform this action content: application/json: schema: $ref: '#/components/schemas/BifrostError' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/BifrostError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/BifrostError' '503': description: Config store not available content: application/json: schema: $ref: '#/components/schemas/BifrostError' security: - ManagementBearerAuth: [] - BasicAuth: [] components: schemas: RelayConfig: type: object description: >- A relay as sent on create and update. Secrets may be plain text or `env.`/`vault.` references. properties: name: type: string pattern: ^[A-Za-z0-9._-]{1,64}$ description: Served at `/relay/{name}`. Immutable once created. description: type: string base_url: type: string format: uri description: >- Upstream origin and base path every relayed request is pinned under. `http` or `https`, no query, fragment or user info. auth: $ref: '#/components/schemas/RelayAuthConfig' credential: $ref: '#/components/schemas/RelayCredential' extra_headers: type: object additionalProperties: description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: >- Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value description: >- Headers sent on every upstream request. A caller cannot replace them. Credential-bearing headers are redacted in responses. network: $ref: '#/components/schemas/RelayNetworkConfig' proxy_config: type: object description: >- Outbound proxy for this relay. Omit to inherit the global proxy when it is enabled for inference. properties: type: type: string enum: - none - http - socks5 - environment url: description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: >- Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value username: description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: >- Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value password: description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: >- Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value ca_cert_pem: description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: >- Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value usage: $ref: '#/components/schemas/RelayUsageConfig' streaming: $ref: '#/components/schemas/RelayStreamingConfig' routes: type: array items: $ref: '#/components/schemas/RelayRouteConfig' skip_route_check: type: boolean default: false description: >- Relay requests that match no `routes[]` entry instead of refusing them with 404. Such calls use the method default for billing and the endpoint usage mapping. ignore_upstream_cost: type: boolean default: false description: >- Drop values read at `cost_path`. The operator's fee and unit pricing still apply. required: - name - base_url example: name: textract description: Amazon Textract base_url: https://textract.us-east-1.amazonaws.com auth: type: aws_sigv4 aws: service: textract credential: aws: access_key: env.AWS_ACCESS_KEY_ID secret_key: env.AWS_SECRET_ACCESS_KEY region: us-east-1 usage: units_path: DocumentMetadata.Pages cost_per_unit: 0.0015 routes: - method: POST path: / headers: X-Amz-Target: Textract.AnalyzeDocument Relay: description: >- A relay as returned by the API - the stored configuration with every secret redacted, plus the path callers use. allOf: - $ref: '#/components/schemas/RelayConfig' - type: object properties: url: type: string description: The path callers send requests to, `/relay/{name}`. required: - url BifrostError: type: object description: Error response from Bifrost properties: event_id: type: string type: type: string is_bifrost_error: type: boolean status_code: type: integer error: $ref: '#/components/schemas/ErrorField' extra_fields: $ref: '#/components/schemas/BifrostErrorExtraFields' RelayAuthConfig: type: object description: How the relay presents its credential to the upstream. properties: type: type: string enum: - bearer - header - query - basic - aws_sigv4 - none default: bearer description: > `bearer` sends `Authorization: Bearer `; `header` sends `: `; `query` appends `?=`; `basic` sends `Authorization: Basic base64()` where the value is `user:password`; `aws_sigv4` signs the request with `credential.aws`; `none` injects nothing. header_name: type: string description: Required for `header`. The header that carries the key. query_param: type: string description: Required for `query`. The query parameter that carries the key. value_prefix: type: string description: For `header`. Literal prefix placed before the key value. aws: $ref: '#/components/schemas/RelayAWSAuthConfig' required: - type RelayCredential: type: object description: > The one secret the relay signs in with. `value` is used by every auth type except `aws_sigv4`, which reads `aws`. Omit for `auth.type: none`. In responses every secret is redacted; an update that sends a redacted placeholder back keeps the stored value. properties: value: description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value aws: $ref: '#/components/schemas/RelayAWSCredential' RelayNetworkConfig: type: object description: Timeouts and connection limits towards the upstream. properties: timeout_seconds: type: integer minimum: 0 default: 60 description: Whole-response timeout for buffered calls. stream_idle_timeout_in_seconds: type: integer minimum: 0 default: 60 description: Longest silence allowed between stream chunks. max_conns_per_host: type: integer minimum: 0 default: 5000 insecure_skip_verify: type: boolean description: Skip upstream TLS certificate verification. ca_cert_pem: type: string description: Extra CA certificate (PEM) to trust for the upstream. RelayUsageConfig: type: object description: > How a call is measured and priced. The endpoint-level block is inherited by every route; a route's `usage` overrides it field by field. Paths are gjson paths into a JSON body (`usage.pages`, `DocumentMetadata.Pages`). Cost is `cost_per_request + extracted cost + billed units * cost_per_unit`. properties: model_path: type: string description: >- Where the model is read - a request body path, or a query parameter when `model_source` is `query`. model_source: type: string enum: - body - query default: body input_tokens_path: type: string description: >- Response body path of the input token count. Token counts are logged, never priced. output_tokens_path: type: string description: Response body path of the output token count. total_tokens_path: type: string description: Response body path of the total token count. cost_path: type: string description: >- Response body path of a provider-reported cost in USD. Arrays are summed. cost_per_request: type: number minimum: 0 description: >- Flat USD fee added to every billable call. A route may set 0 to waive the endpoint fee. units_path: type: string description: >- Path of the billable quantity (pages, credits, text). Ignored for `body_bytes` and `body_chars`. units_source: type: string enum: - response - request default: response description: >- Which body the quantity is read from - what the upstream reports, or what the caller sent. units_measure: type: string enum: - value - chars - body_bytes - body_chars default: value description: > `value` is the number at `units_path`; `chars` the character count of the string there; `body_bytes` the byte length of the whole body; `body_chars` the character count of the whole body, any content type. cost_per_unit: type: number minimum: 0 description: USD per billed unit. units_block_size: type: number exclusiveMinimum: 0 description: >- Bill per started block of this many raw units (for example 100 characters). Unset bills the raw quantity exactly; an explicit 1 rounds fractional quantities up. units_minimum: type: number minimum: 0 default: 0 description: Least number of billed units once a quantity was read. RelayStreamingConfig: type: object description: Which requests are relayed as streams rather than buffered. properties: paths: type: array items: type: string description: > Path globs whose replies are always relayed as streams. Elsewhere a route's `stream` flag decides, and without one the upstream reply does - a `text/event-stream` response streams, anything else is buffered and priced. Nothing the caller sends (`Accept`, a `stream` flag) selects streaming. RelayRouteConfig: type: object description: > One upstream operation. Routes are matched in order, first match wins. Without `skip_route_check`, a request matching no route is refused with 404. properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE - HEAD path: type: string description: >- Segment glob below the endpoint, for example `/v1/search` or `/jobs/*`. A trailing `/**` matches the prefix and everything below it. headers: type: object additionalProperties: type: string description: > Request headers that must also match - header name (case-insensitive) to a value glob, for example `X-Amz-Target: Textract.Get*`. enabled: type: boolean default: true description: When false, requests matching the route are refused with 404. billable: type: boolean description: >- When false the call is relayed but neither counted nor charged. Defaults to true for POST and false for every other method. stream: type: boolean description: >- Forces the streaming (true) or buffered (false) relay for this route. usage: $ref: '#/components/schemas/RelayUsageConfig' required: - method - path ErrorField: type: object properties: type: type: string code: type: string message: type: string param: type: string event_id: type: string BifrostErrorExtraFields: type: object properties: routing_info: $ref: '#/components/schemas/RoutingInfo' provider: $ref: '#/components/schemas/ModelProvider' deprecated: true description: 'Deprecated: use routing_info.provider.' original_model_requested: type: string deprecated: true description: >- Deprecated: use routing_info.primary_model when routing_info.is_fallback is true, otherwise routing_info.model. For the model the caller asked for, read routing_info.requested_model. resolved_model_used: type: string deprecated: true description: >- Deprecated: use routing_info.resolved_key_alias.model_id when an alias matched, otherwise routing_info.model. request_type: type: string mcp_request_type: type: string a2a_request_type: type: string description: Agent Gateway operation, for A2A errors a2a_agent_name: type: string error_type: type: string description: >- Normalized, low-cardinality classification of why the request failed, declared by whichever component refused it. Prefixed by fault domain (caller_, policy_, provider_, bifrost_). Absent on failures that were not classified at source. retry_after_ms: type: integer format: int64 minimum: 1000 maximum: 300000 description: >- The provider's hint for how long to wait before retrying, in milliseconds, read from its retry-after-ms or Retry-After header or its google.rpc.RetryInfo error detail, and clamped to between 1000 and 300000. Absent when the provider gave no explicit hint. raw_request: description: Raw provider request, when raw request capture is enabled raw_response: description: Raw provider response, when raw response capture is enabled converted_request_type: type: string dropped_compat_plugin_params: type: array items: type: string latency: type: integer format: int64 description: Latency in milliseconds key_statuses: type: array description: >- Per-key results, for requests that ran on every key such as listing models items: type: object properties: key_id: type: string status: type: string enum: - success - list_models_failed provider: $ref: '#/components/schemas/ModelProvider' error: $ref: '#/components/schemas/BifrostError' mcp_auth_required: type: object description: >- Set when a per-user MCP tool needs the caller to complete an inline auth flow properties: kind: type: string mcp_client_id: type: string mcp_client_name: type: string message: type: string authorize_url: type: string session_id: type: string subject_token_missing: type: boolean description: >- token_exchange only. True when there was nothing to exchange, including when the caller's Bifrost sign-in has expired; message says which exchange_error: type: string description: >- token_exchange only. The identity provider's error code and description when it refused the exchange billed_usage: $ref: '#/components/schemas/BifrostLLMUsage' description: >- Usage the provider reported and billed even though the request failed RelayAWSAuthConfig: type: object description: >- SigV4 settings for `aws_sigv4`. The signing region is `credential.aws.region`. properties: service: type: string pattern: ^[a-z0-9-]+$ description: SigV4 signing name, for example `textract` or `translate`. required: - service RelayAWSCredential: type: object description: AWS credential for `aws_sigv4`. Static keys, or a role to assume. properties: access_key: description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value secret_key: description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value session_token: description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value region: description: Signing region. Required. oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value role_arn: description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value external_id: description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value session_name: description: > A secret-capable value. Serialized as an object with the resolved `value` plus reference metadata; on input, a bare string is also accepted — plain text, `env.VAR_NAME`, or `vault.path/to/secret` (references resolve at runtime and only the reference is persisted). oneOf: - type: string description: >- Bare input form — plain text, `env.VAR_NAME`, or `vault.path/to/secret` - type: object description: Resolved form, as returned by GET responses properties: value: type: string description: Resolved value (redacted in GET responses for secret fields) ref: type: string description: >- Source reference (`env.VAR_NAME` or `vault.path`); empty for plain-text values type: type: string enum: - plain_text - env - vault description: Source type of the value required: - region RoutingInfo: type: object description: >- Which provider, model and key handled the attempt that produced this response or error, and what the caller asked for. Also sent as x-bifrost-routing-info-* response headers. properties: provider: $ref: '#/components/schemas/ModelProvider' description: Provider that ran the attempt model: type: string description: Model sent to that provider key: type: string description: Name of the stored key used, never its ID or secret resolved_key_alias: $ref: '#/components/schemas/ResolvedKeyAlias' is_fallback: type: boolean description: >- True when a fallback served the request or returned the error. Omitted when false. primary_provider: $ref: '#/components/schemas/ModelProvider' description: The primary attempt's provider. Set only when a fallback ran. primary_model: type: string description: The primary attempt's model. Set only when a fallback ran. requested_provider: $ref: '#/components/schemas/ModelProvider' description: >- Provider the caller asked for, before routing rules, load balancing or session affinity changed it. Omitted when the caller sent a bare model. requested_model: type: string description: Model the caller asked for, before anything changed it server_side_fallback_model: type: string description: Model that answered when Anthropic switched models inside one call ModelProvider: type: string description: AI model provider identifier enum: - anthropic - azure - bedrock - bedrock_mantle - sagemaker - cerebras - cohere - deepseek - gemini - groq - mistral - ollama - opencode-go - opencode-zen - openai - parasail - perplexity - sgl - vertex - openrouter - elevenlabs - huggingface - nebius - xai - replicate - vllm - runway - runware - fireworks - sarvam - wafer - databricks - cloudflare - typesafe - minimax - byteplus BifrostLLMUsage: type: object description: Token usage information properties: prompt_tokens: type: integer description: > Total input tokens including any prompt-cache tokens (read + write). Subtract prompt_tokens_details.cached_read_tokens and prompt_tokens_details.cached_write_tokens to get the non-cached portion. prompt_tokens_details: $ref: '#/components/schemas/ChatPromptTokensDetails' completion_tokens: type: integer description: Number of output/completion tokens generated. completion_tokens_details: $ref: '#/components/schemas/ChatCompletionTokensDetails' total_tokens: type: integer tool_usage: type: object description: | Counts of provider-hosted (server-side) tool calls billed per call. properties: web_search: type: object properties: num_requests: type: integer description: Number of billable web search calls. cost: $ref: '#/components/schemas/BifrostCost' ResolvedKeyAlias: type: object description: Set only when the requested model matched a model alias on the key required: - model_id properties: model_id: type: string description: Model ID sent to the provider model_name: type: string description: Canonical model name, used for pricing and logs model_family: type: string description: Resolved model family ChatPromptTokensDetails: type: object properties: text_tokens: type: integer audio_tokens: type: integer image_tokens: type: integer cached_read_tokens: type: integer description: > Tokens served from the prompt cache (cache hit). These tokens are already included in prompt_tokens and are billed at the reduced cache-read rate. Populated for all providers that support prompt caching (Anthropic, Bedrock, OpenAI, Gemini, xAI, etc.). cached_write_tokens: type: integer description: > Tokens written to the prompt cache on this request (cache creation / write). These tokens are already included in prompt_tokens and are billed at the cache-creation rate. Populated for providers that separately report cache write tokens (Anthropic, Bedrock). ChatCompletionTokensDetails: type: object properties: text_tokens: type: integer accepted_prediction_tokens: type: integer audio_tokens: type: integer citation_tokens: type: integer num_search_queries: type: integer deprecated: true description: >- Deprecated, use tool_usage.web_search.num_requests. Will be removed in 3.0.0. reasoning_tokens: type: integer image_tokens: type: integer rejected_prediction_tokens: type: integer BifrostCost: type: object description: Cost breakdown for the request properties: input_tokens_cost: type: number output_tokens_cost: type: number reasoning_tokens_cost: type: number description: Cost for reasoning/thinking tokens (reasoning models) citation_tokens_cost: type: number description: Cost for citation tokens search_queries_cost: type: number description: Cost for web search queries request_cost: type: number total_cost: type: number securitySchemes: BearerAuth: type: http scheme: bearer description: > Bearer token authentication. Use your provider API key or Bifrost authentication token. Virtual keys (prefixed with `sk-bf-`) can also be passed here. BasicAuth: type: http scheme: basic description: > Basic authentication using the Bifrost admin username and password (`auth_config.admin_username` / `auth_config.admin_password`). Accepted on management APIs (`/api/*`, `/metrics`, `/ws`) only - the inference middleware never validates Basic credentials. ApiKeyAuth: type: apiKey in: header name: x-api-key description: | API key authentication via the `x-api-key` header. Virtual keys (prefixed with `sk-bf-`) can also be passed here. ManagementBearerAuth: type: http scheme: bearer description: > Management API authentication for `/api/*` endpoints. Use the `Authorization` header with `Bearer `, where `` is one of: - a Bifrost management API key, - a dashboard session token issued by `POST /api/session/login`, - base64 of `:` (legacy equivalent of `BasicAuth`). Virtual keys (`sk-bf-*`) and the `x-api-key` header are not accepted on management APIs - the sole exception is `GET /api/governance/virtual-keys/quota`, which is virtual-key-only. Authentication alone is not sufficient in Bifrost Enterprise: each operation page shows a **Required Permissions** table (`Resource:Operation`, for example `Dashboard:View`) above its Authorizations section, and the caller's RBAC role or management API key scopes must include what it lists, otherwise the request is rejected with `403 Forbidden`. A local admin — authenticated with the admin password, or any caller on a deployment with dashboard auth disabled — bypasses these checks and can call every management endpoint. **OSS setup lock.** On Bifrost OSS, while dashboard auth is not active (no admin account, or auth disabled), every management endpoint except the public ones (`/health`, `/api/version`, `/api/session/is-auth-enabled`, `/api/session/login`, ...) requires the operator's setup token in the `X-Bifrost-Setup-Token` header, in place of `Authorization`. The token is set with `setup_token` in `config.json` or the `BIFROST_SETUP_TOKEN` environment variable. A missing header returns `401`, a wrong token `403`. The header stops working once dashboard auth is enabled. The dashboard instead trades the token once for an HttpOnly `bifrost_setup_session` cookie via `POST /api/session/setup`. See [Required permissions](/api/procuring-api-keys#required-permissions) for how permissions are derived and which endpoints are exempt. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.