> ## 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 a model router's routing

> Changes which requests the router takes: whether it is on, its scope, its condition and its priority within the scope. Each field the body sends replaces the stored value and an omitted field keeps it, as in a routing rule update, so `{"enabled": false}` turns the router off and leaves the rest as it is. A `cel_expression` sent without `query` clears the stored builder state, which described the old condition. Unknown fields are refused with 400. Routers are tried after the routing rules, on the request as the routing rules left it: narrowest scope first (virtual key, user, team, customer, global), by priority within a scope. The first enabled router whose condition holds classifies the request as SIMPLE, MEDIUM or COMPLEX, and its target for that tier replaces the provider and model; no other router is tried. A condition of model == "<name>" lets apps ask for the router by that model name. The condition cannot use complexity_tier. Priorities are unique within a scope among model routers, separate from routing rule priorities. The router's classifier and targets are left as they are.


**Required Permissions**

| Permission | Granted via |
| - | - |
| `Routers: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/routing/model-routers/{router_id}/routing
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,
          or https://mycompany.com/bifrost when served under server.base_path)
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/routing/model-routers/{router_id}/routing:
    parameters:
      - name: router_id
        in: path
        required: true
        description: Model router id.
        schema:
          type: string
    put:
      tags:
        - Routing
      summary: Update a model router's routing
      description: >
        Changes which requests the router takes: whether it is on, its scope,
        its condition and its priority within the scope. Each field the body
        sends replaces the stored value and an omitted field keeps it, as in a
        routing rule update, so `{"enabled": false}` turns the router off and
        leaves the rest as it is. A `cel_expression` sent without `query` clears
        the stored builder state, which described the old condition. Unknown
        fields are refused with 400. Routers are tried after the routing rules,
        on the request as the routing rules left it: narrowest scope first
        (virtual key, user, team, customer, global), by priority within a scope.
        The first enabled router whose condition holds classifies the request as
        SIMPLE, MEDIUM or COMPLEX, and its target for that tier replaces the
        provider and model; no other router is tried. A condition of model ==
        "<name>" lets apps ask for the router by that model name. The condition
        cannot use complexity_tier. Priorities are unique within a scope among
        model routers, separate from routing rule priorities. The router's
        classifier and targets are left as they are.
      operationId: setModelRouterRouting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                A change to a model router's routing. Each field sent replaces
                the stored value; an omitted field keeps it. A non-global scope
                needs a scope_id, sent or already stored.
              additionalProperties: false
              properties:
                enabled:
                  type: boolean
                  description: Whether the router takes requests.
                scope:
                  type: string
                  enum:
                    - global
                    - team
                    - customer
                    - virtual_key
                    - user
                  description: Scope level. Changing to global drops scope_id.
                scope_id:
                  type:
                    - string
                    - 'null'
                  description: >-
                    ID of the scope's entity. The team, customer or virtual key
                    must exist (400 otherwise); a user scope_id is not checked.
                cel_expression:
                  type: string
                  description: >-
                    CEL condition over the request as the routing rules left it;
                    empty takes every request in the scope. Cannot use
                    complexity_tier. Sent without query, it clears the stored
                    builder state.
                query:
                  type:
                    - object
                    - 'null'
                  description: >-
                    Visual condition builder state for cel_expression. Not
                    evaluated.
                priority:
                  type: integer
                  minimum: 0
                  description: >-
                    Order within the scope; lower is tried first. A priority
                    another router in the same scope holds returns 409.
      responses:
        '200':
          description: Model router routing saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelRouter'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
        '409':
          description: Conflict with the current state of the resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
      security:
        - ManagementBearerAuth: []
        - BasicAuth: []
components:
  schemas:
    ModelRouter:
      type: object
      description: >-
        A model router - an id, a name and a description beside the same
        settings as ComplexityAnalyzerConfig, sent and returned at the top
        level; its phrase suggestions, which only model routers make; the model
        each tier gets; and the routing that decides which requests it takes.
        Routers are separate from the complexity analyzer config, which routing
        rules read complexity_tier from. The cross-field rules of
        ComplexityAnalyzerConfig apply, and the suggestion rules below.
      additionalProperties: false
      allOf:
        - if:
            not:
              required:
                - classifier
              properties:
                classifier:
                  enum:
                    - decision
                    - llm
            properties:
              session:
                properties:
                  enabled:
                    const: true
                required:
                  - enabled
            required:
              - session
          then:
            required:
              - semantic
        - if:
            properties:
              semantic:
                properties:
                  fallback:
                    const: llm
                required:
                  - fallback
            required:
              - semantic
          then:
            required:
              - llm
        - if:
            properties:
              suggestions:
                properties:
                  enabled:
                    const: true
                required:
                  - enabled
            required:
              - suggestions
          then:
            required:
              - semantic
            not:
              required:
                - classifier
              properties:
                classifier:
                  enum:
                    - decision
                    - llm
        - if:
            properties:
              suggestions:
                properties:
                  enabled:
                    const: true
                required:
                  - enabled
                not:
                  required:
                    - provider
                    - model
            required:
              - suggestions
          then:
            required:
              - llm
        - if:
            properties:
              classifier:
                const: llm
            required:
              - classifier
          then:
            required:
              - llm
      required:
        - name
        - keywords
      properties:
        id:
          type: string
          maxLength: 64
          pattern: ^[A-Za-z0-9_-]+$
          not:
            const: defaults
          description: >-
            Stable router id; generated when omitted on create. `defaults` is
            reserved, since it names the endpoint that serves a new router's
            defaults.
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Display name, unique across routers.
        description:
          type: string
        tier_boundaries:
          type: object
          deprecated: true
          description: >
            Deprecated score thresholds for the retired lexical complexity
            classifier.

            This block is optional and ignored by semantic classification, but
            remains

            accepted for backward compatibility. When supplied, values must
            satisfy

            0 < simple_medium < medium_complex < 1.
          additionalProperties: false
          required:
            - simple_medium
            - medium_complex
          properties:
            simple_medium:
              type: number
              deprecated: true
              description: >-
                Deprecated score boundary between SIMPLE and MEDIUM tiers
                (ignored by semantic classification)
              exclusiveMinimum: 0
              exclusiveMaximum: 1
            medium_complex:
              type: number
              deprecated: true
              description: >-
                Deprecated score boundary between MEDIUM and COMPLEX tiers
                (ignored by semantic classification)
              exclusiveMinimum: 0
              exclusiveMaximum: 1
        keywords:
          type: object
          description: >
            Reference phrases for semantic complexity classification, one list
            per tier.

            Each request is embedded and takes the tier of its nearest phrase.
            Entries

            should be whole example prompts rather than individual keywords.
            Each phrase

            is limited to 2000 characters, the normalized lists may contain at
            most 750

            phrases combined, and the same phrase cannot appear in two tiers.
            The field

            names predate semantic classification and are kept for backward
            compatibility.
          additionalProperties: false
          required:
            - simple_keywords
            - medium_keywords
            - complex_keywords
          properties:
            simple_keywords:
              type: array
              description: Reference phrases for the SIMPLE tier (50 built-in defaults)
              items:
                type: string
                maxLength: 2000
              minItems: 1
            medium_keywords:
              type: array
              description: Reference phrases for the MEDIUM tier (50 built-in defaults)
              items:
                type: string
                maxLength: 2000
              minItems: 1
            complex_keywords:
              type: array
              description: Reference phrases for the COMPLEX tier (50 built-in defaults)
              items:
                type: string
                maxLength: 2000
              minItems: 1
        classifier:
          type: string
          enum:
            - semantic
            - decision
            - llm
          default: semantic
          description: >-
            Primary complexity classifier. llm classifies with the model in the
            llm block.
        semantic:
          type: object
          description: >
            Embedding configuration for semantic complexity classification. When
            absent,

            no complexity tier is published and rules referencing
            complexity_tier fall

            through. The provider must have an enabled key.
          additionalProperties: false
          required:
            - provider
            - embedding_model
          properties:
            provider:
              type: string
              minLength: 1
              description: Provider used for embedding calls (must have an enabled key)
            embedding_model:
              type: string
              minLength: 1
              description: Embedding model, e.g. text-embedding-3-small
            timeout:
              description: >-
                Ceiling on the inline embedding call. Accepts a duration string
                ("1.5s") or milliseconds as a number. Default 1.5s; exceeding it
                publishes no tier for that request.
              oneOf:
                - type: string
                  pattern: ^[0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h)$
                - type: number
                  exclusiveMinimum: 0
            min_similarity:
              type: number
              minimum: 0
              exclusiveMaximum: 1
              description: >-
                Similarity floor for the nearest reference phrase; below it no
                tier is published. 0 (default) accepts the nearest eligible
                match. Compared against the vector store backend's own
                similarity scale (raw cosine for chromem/Qdrant/Pinecone/Redis,
                certainty for Weaviate).
            message_history_count:
              type: integer
              minimum: 1
              maximum: 10
              description: >-
                Number of recent user messages joined oldest-first into the
                embedded text. 1 (default) embeds only the latest message.
                System prompts and assistant replies are never embedded.
            count_toward_budgets:
              type: boolean
              description: >-
                Whether embedding usage counts toward virtual-key budgets
                (default false)
            vector_store:
              type: string
              enum:
                - embedded
                - vector_store
              description: >
                Where reference-phrase embeddings live. `embedded` (default)
                uses the

                built-in in-memory store, so phrases are re-embedded on every
                restart.

                `vector_store` uses the top-level `vector_store` when one is
                configured

                and falls back to the embedded store otherwise.
            fallback:
              type: string
              enum:
                - none
                - llm
                - decision
              description: >
                What answers when semantic classification produces no tier.
                `none`

                (the default) records the request as skipped, `llm` uses the
                configured

                chat model, and `decision` uses the configured decision model.
        decision:
          type: object
          description: >-
            Decision-model complexity-classifier request settings. Credentials
            come from the selected provider's configuration.
          additionalProperties: false
          properties:
            provider:
              type: string
              description: >-
                Provider serving the decision model, e.g. `typesafe`,
                `cloudflare` (Clef), or a custom provider with
                `base_provider_type` `typesafe` (Laya, Nimble). Set together
                with `model`; leave both empty for `typesafe`/`jev-latest`.
            model:
              type: string
              description: >-
                Decision model on that provider, e.g. `jev-latest`,
                `@cf/cloudflare/clef-flash`, `nimble-latest`, `english`. Set
                together with `provider`; leave both empty for
                `typesafe`/`jev-latest`.
            previous_message_count:
              type: integer
              minimum: 0
              maximum: 5
              default: 1
              description: >-
                Number of preceding user messages sent with the current user
                request. Assistant messages are excluded.
            timeout:
              description: >-
                Maximum decision-model classification latency. Accepts a
                duration string or milliseconds as a number; default 1500ms.
              oneOf:
                - type: string
                  pattern: ^[0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h)$
                - type: number
                  minimum: 0
            min_confidence:
              type: number
              minimum: 0
              maximum: 1
              default: 0
              description: >-
                Confidence an answer must reach to publish its tier. An answer
                below it publishes no tier. A missing confidence is derived from
                the tier probabilities; an answer with neither is kept. 0 keeps
                every answer.
            criteria:
              type: object
              description: >-
                Per-tier overrides of the shipped decision-model definitions,
                signals, and examples. Any tier or field left out sends the
                default.
              additionalProperties: false
              properties:
                SIMPLE:
                  type: object
                  additionalProperties: false
                  properties:
                    definition:
                      type: string
                      maxLength: 500
                      description: >-
                        Replaces this tier's shipped definition. Omit to use the
                        default.
                    signals:
                      type: array
                      maxItems: 12
                      items:
                        type: string
                        maxLength: 300
                      description: >-
                        Replaces this tier's shipped signals. Omit to use the
                        default.
                    examples:
                      type: array
                      maxItems: 12
                      items:
                        type: string
                        maxLength: 300
                      description: >-
                        Replaces this tier's shipped examples. Omit to use the
                        default.
                MEDIUM:
                  type: object
                  additionalProperties: false
                  properties:
                    definition:
                      type: string
                      maxLength: 500
                      description: >-
                        Replaces this tier's shipped definition. Omit to use the
                        default.
                    signals:
                      type: array
                      maxItems: 12
                      items:
                        type: string
                        maxLength: 300
                      description: >-
                        Replaces this tier's shipped signals. Omit to use the
                        default.
                    examples:
                      type: array
                      maxItems: 12
                      items:
                        type: string
                        maxLength: 300
                      description: >-
                        Replaces this tier's shipped examples. Omit to use the
                        default.
                COMPLEX:
                  type: object
                  additionalProperties: false
                  properties:
                    definition:
                      type: string
                      maxLength: 500
                      description: >-
                        Replaces this tier's shipped definition. Omit to use the
                        default.
                    signals:
                      type: array
                      maxItems: 12
                      items:
                        type: string
                        maxLength: 300
                      description: >-
                        Replaces this tier's shipped signals. Omit to use the
                        default.
                    examples:
                      type: array
                      maxItems: 12
                      items:
                        type: string
                        maxLength: 300
                      description: >-
                        Replaces this tier's shipped examples. Omit to use the
                        default.
        llm:
          type: object
          description: >
            Chat-completion (LLM) classifier settings. Used as the primary
            classifier

            when `classifier` is `llm`, and as the fallback when
            `semantic.fallback`

            selects `llm`, where it runs only after semantic classification
            produces no

            tier. Otherwise the block is kept but not used. Tier names (SIMPLE,
            MEDIUM,

            COMPLEX) and the response format are fixed: the gateway always
            appends a

            non-editable reinforcement stating them.
          additionalProperties: false
          required:
            - provider
            - model
          properties:
            provider:
              type: string
              minLength: 1
              description: >-
                Provider used to run the classification chat completion (must
                have an enabled key)
            model:
              type: string
              minLength: 1
              description: >-
                Chat model asked to name the tier. Every classification it makes
                waits on one completion from this model, so pick a small, fast
                one.
            timeout:
              description: >-
                Per-request classification timeout. Accepts a duration string
                ("2s") or milliseconds as a number. Default 4s. On timeout no
                complexity tier is published and the request is recorded as
                skipped.
              oneOf:
                - type: string
                  pattern: ^[0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h)$
                - type: number
                  exclusiveMinimum: 0
            prompt:
              type: string
              maxLength: 4000
              description: >-
                Replaces the shipped classification guidance (max 4000
                characters); empty means the shipped guidance is used. The
                tier-name and response-format reinforcement is appended by the
                gateway either way and cannot be edited.
            message_history_count:
              type: integer
              minimum: 1
              maximum: 10
              description: >-
                How many of the most recent user messages are given to the
                classifier, oldest first (default 1, the latest message only).
                Only user turns count; system prompts and assistant replies are
                never sent.
            count_toward_budgets:
              type: boolean
              description: >-
                Whether classification completion cost counts toward virtual-key
                budgets (record-only, never enforced; default false)
        session:
          type: object
          description: >-
            Session-aware complexity routing. When enabled and a supported
            session identity is present, Bifrost retains the highest tier
            observed across normally sequential turns for 24 hours of
            inactivity. It uses the configured primary classifier and is
            independent of provider session stickiness.
          additionalProperties: false
          required:
            - enabled
          properties:
            enabled:
              type: boolean
              description: Enable monotonic session tier retention; default is false.
        suggestions:
          type: object
          description: >-
            Phrase suggestions for the semantic router. When enabled, a sample
            of the vectors the semantic classifier already computes is kept
            under each request's log ID (request text stays in the logs), and a
            run on the schedule clusters that traffic and asks the suggestion
            model for phrases. Vectors are captured only into the top-level
            vector_store, and not when that is Chromem, which keeps them in each
            gateway's memory; with no vector_store, or only the semantic
            classifier's embedded store, nothing is captured and no run has
            traffic to read. Captured vectors are deleted with their logs, and
            become due for deletion after lookback_days or the log retention,
            whichever is shorter; an hourly cleanup removes them, so one can
            remain up to an hour past that, and longer while the vector store is
            unavailable.
          additionalProperties: false
          required:
            - enabled
          properties:
            enabled:
              type: boolean
              description: >-
                Capture a sample of classified requests and run suggestions on
                the schedule; default false. Runs started through the API need
                this block and a suggestion model (provider and model here, or
                an llm block), not enabled; a router left at false runs
                suggestions only on demand, each run first embedding the
                router's logged requests in its window that are not yet captured
                - the sample_rate share of those whose content was logged, up to
                max_clustered_requests per run and newest first, so a smaller
                backlog is embedded in full and older requests past the limit
                wait for later runs. A run started without a suggestion model is
                accepted and then fails. Estimates and impact replays need this
                block but not the suggestion model, which they do not call.
                Capture needs a top-level vector_store other than Chromem;
                without one, enabling captures nothing. Enabling requires the
                semantic classifier as the primary classifier (a semantic block,
                classifier not decision) and a suggestion model (provider and
                model here, or an llm block).
            sample_rate:
              type: number
              exclusiveMinimum: 0
              maximum: 1
              description: Share of classified requests captured; default 0.1.
            lookback_days:
              type: integer
              minimum: 1
              maximum: 90
              description: >-
                Days of captured traffic a run draws on, and how long captured
                vectors are kept; default 7.
            schedule:
              type: object
              description: >-
                When suggestion runs start - at start_at and every fixed
                interval after it, the same on every node. Default daily at
                03:00 UTC.
              additionalProperties: false
              properties:
                every:
                  type: string
                  pattern: ^([1-9]|1[0-9]|2[0-3])h$|^([1-9]|[12][0-9]|30)d$|^[1-4]w$
                  description: >-
                    The interval, as a fixed duration - hours (1h-23h), days
                    (1d-30d) or weeks (1w-4w). Default 1d.
                  example: 1d
                start_at:
                  type: string
                  format: date-time
                  description: >-
                    The first run, an RFC 3339 time such as
                    2026-11-12T03:00:00Z. Runs repeat every interval from it, so
                    it also sets the time of day (in UTC - a daily run moves by
                    an hour of local time across a daylight-saving change).
                    Default 1970-01-01T03:00:00Z.
                  example: '2026-11-12T03:00:00Z'
            max_clustered_requests:
              type: integer
              minimum: 1000
              maximum: 100000
              description: >-
                Most captured requests one run clusters; the rest of the window
                is counted into the clusters found. Default 20000.
            min_cluster_requests:
              type: integer
              minimum: 2
              maximum: 1000
              description: >-
                Smallest cluster, in requests, a suggestion is written for;
                default 6. A run raises it to 0.1% of the requests in its window
                when that is larger.
            provider:
              type: string
              minLength: 1
              description: >-
                Provider of the suggestion model. Set together with model; both
                omitted use the llm block's model.
            model:
              type: string
              minLength: 1
              description: >-
                Suggestion model. Set together with provider; both omitted use
                the llm block's model.
            instructions:
              type: string
              maxLength: 8000
              description: >-
                Replaces the shipped suggestion instructions (served as
                suggestion_default_instructions by the status endpoint). Tier
                definitions and the fixed output and safety rules are added
                either way.
            tier:
              type: object
              description: >-
                How each suggestion's tier is decided, after its phrases are
                written. Omitted: the llm classifier on the phrase model.
              properties:
                classifier:
                  type: string
                  enum:
                    - llm
                    - decision
                  description: >-
                    llm: a chat model prompted with instructions, the tier
                    definitions, and the router's own phrases as examples.
                    decision: a decision model asked one choice question with
                    the router's tier definitions and its own phrases as
                    examples. Shipped default phrases are never used as
                    examples.
                provider:
                  type: string
                  minLength: 1
                  description: >-
                    Provider of the tier model. Set together with model; both
                    omitted take the phrase model (llm) or the decision block's
                    model, else the shipped decision model (decision), when the
                    config is saved.
                model:
                  type: string
                  minLength: 1
                  description: Tier model. Set together with provider.
                prompt:
                  type: string
                  maxLength: 16000
                  description: >-
                    llm only: the whole tier prompt (instructions, tier
                    definitions and examples), sent as written followed by the
                    fixed output and safety rules. Empty: generated by each run
                    from the router's tier definitions and its own phrases. The
                    generated text is served as suggestion_default_tier_prompt
                    by the model router status endpoint.
                instructions:
                  type: string
                  maxLength: 8000
                  description: >-
                    decision only: the choice question's instructions, sent as
                    written. Empty: the shipped instructions. Served as
                    suggestion_default_tier_instructions.
                criteria:
                  type: object
                  description: >-
                    decision only: each tier's definition, signals and examples,
                    sent as written as that tier's choice. A tier left out is
                    generated from the router (its decision definitions and
                    signals, its own phrases as examples). The generated
                    criteria are served as suggestion_default_tier_criteria.
                  properties:
                    SIMPLE:
                      type: object
                      properties:
                        definition:
                          type: string
                          minLength: 1
                          maxLength: 500
                        signals:
                          type: array
                          maxItems: 12
                          items:
                            type: string
                            maxLength: 300
                        examples:
                          type: array
                          maxItems: 12
                          items:
                            type: string
                            maxLength: 300
                      required:
                        - definition
                      additionalProperties: false
                    MEDIUM:
                      type: object
                      properties:
                        definition:
                          type: string
                          minLength: 1
                          maxLength: 500
                        signals:
                          type: array
                          maxItems: 12
                          items:
                            type: string
                            maxLength: 300
                        examples:
                          type: array
                          maxItems: 12
                          items:
                            type: string
                            maxLength: 300
                      required:
                        - definition
                      additionalProperties: false
                    COMPLEX:
                      type: object
                      properties:
                        definition:
                          type: string
                          minLength: 1
                          maxLength: 500
                        signals:
                          type: array
                          maxItems: 12
                          items:
                            type: string
                            maxLength: 300
                        examples:
                          type: array
                          maxItems: 12
                          items:
                            type: string
                            maxLength: 300
                      required:
                        - definition
                      additionalProperties: false
                  additionalProperties: false
              additionalProperties: false
              dependentRequired:
                provider:
                  - model
                model:
                  - provider
          dependentRequired:
            provider:
              - model
            model:
              - provider
        targets:
          type: array
          readOnly: true
          description: >-
            The model each tier gets. Returned with the router; set with PUT
            /api/routing/model-routers/{router_id}/targets. Ignored in a create
            or update body.
          items:
            $ref: '#/components/schemas/ModelRouterTarget'
        routing:
          allOf:
            - $ref: '#/components/schemas/ModelRouterRouting'
          description: >-
            Which requests the router takes. Always returned. Optional on
            create, where omitting it starts the router off, global, with the
            priority after the last global router. Ignored in an update body;
            set it with PUT /api/routing/model-routers/{router_id}/routing.
    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'
    ModelRouterTarget:
      type: object
      description: >-
        One model for one tier of a model router. Omitting provider or model
        keeps the request's value, but a target sets at least one.
      additionalProperties: false
      required:
        - tier
        - weight
      anyOf:
        - required:
            - provider
          properties:
            provider:
              type: string
              minLength: 1
        - required:
            - model
          properties:
            model:
              type: string
              minLength: 1
      dependentRequired:
        key_id:
          - provider
      properties:
        tier:
          type: string
          enum:
            - SIMPLE
            - MEDIUM
            - COMPLEX
        provider:
          type:
            - string
            - 'null'
          description: >-
            Target provider (omit to keep the request's provider). Moving to
            another provider clears a key the routing rules pinned.
        model:
          type:
            - string
            - 'null'
          description: Target model (omit to keep the request's model)
        key_id:
          type:
            - string
            - 'null'
          description: UUID of the API key to pin for this target
        weight:
          type: number
          format: double
          exclusiveMinimum: 0
          description: Probability weight within the tier; the weights of a tier sum to 1.
        fallbacks:
          type: array
          description: >-
            Fallback chain used when this target is chosen. A non-empty list
            replaces the request's chain; omit it or send [] to keep the chain
            the routing rules set.
          items:
            description: >-
              A fallback in a routing rule's chain. Either the "provider/model"
              string ("provider/" keeps the incoming model), or an object that
              additionally pins a provider key.
            oneOf:
              - type: string
                minLength: 1
              - type: object
                required:
                  - provider
                properties:
                  provider:
                    type: string
                    minLength: 1
                    description: Fallback provider
                  model:
                    type:
                      - string
                      - 'null'
                    description: >-
                      Fallback model (omit or empty to use the incoming request
                      model)
                  key_id:
                    type:
                      - string
                      - 'null'
                    description: >-
                      UUID of the API key to pin for this fallback (omit for
                      load-balanced key selection). A fallback whose pinned key
                      is missing from the provider's pool is skipped.
                additionalProperties: false
    ModelRouterRouting:
      type: object
      description: >-
        Which requests a model router takes. Routers are tried after the routing
        rules, on the request as the routing rules left it - narrowest scope
        first (virtual key, user, team, customer, global), by priority within a
        scope - and the first enabled router whose condition holds classifies
        the request. No other router is tried.
      additionalProperties: false
      allOf:
        - if:
            required:
              - scope
            properties:
              scope:
                not:
                  const: global
          then:
            required:
              - scope_id
            properties:
              scope_id:
                type: string
                minLength: 1
      properties:
        enabled:
          type: boolean
          default: false
          description: Whether the router takes requests.
        scope:
          type: string
          enum:
            - global
            - team
            - customer
            - virtual_key
            - user
          default: global
          description: >-
            Scope level. The team, customer or virtual key named by scope_id
            must exist (400 otherwise); a user scope_id is not checked.
        scope_id:
          type:
            - string
            - 'null'
          description: >-
            ID of the scope's entity. Required when scope is not global; dropped
            for global.
        cel_expression:
          type: string
          description: >-
            Optional CEL condition over the request as the routing rules left
            it. Empty takes every request in the scope. A condition of model ==
            "<name>" lets apps ask for the router by that model name. Cannot use
            complexity_tier, which the router decides once it takes the request.
        query:
          type:
            - object
            - 'null'
          description: >-
            Visual condition builder state (react-querybuilder combinator and
            rules). Not evaluated; cel_expression is.
        priority:
          type: integer
          minimum: 0
          default: 0
          description: >-
            Order within the scope; lower is tried first. Unique within the same
            scope and scope_id among model routers, separate from routing rule
            priorities; a duplicate returns 409.
    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'
        fallback_attempts:
          type: array
          description: >-
            Set when the primary and every fallback failed and the primary's
            error was returned: what became of each fallback, in chain order. A
            fallback refused before reaching its provider (for example by a
            virtual key that does not allow it) is only visible here.
          items:
            type: object
            properties:
              provider:
                $ref: '#/components/schemas/ModelProvider'
              model:
                type: string
              status_code:
                type: integer
              type:
                type: string
              message:
                type: string
              skipped:
                type: boolean
                description: >-
                  The fallback was never attempted (no provider config, or the
                  request type has no fallback support)
        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
    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
        - machgen
        - baseten
        - kimchi
        - soniox
    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 <token>`, where `<token>` is one of:


        - a Bifrost management API key,

        - a dashboard session token issued by `POST /api/session/login`,

        - base64 of `<admin-username>:<admin-password>` (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.