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

# Retry a model router's failed warmup

> Restarts one router's semantic classifier warmup when its state is failed. The retry runs asynchronously.

**Required Permissions**

| Permission | Granted via |
| - | - |
| `Routers:Create` | 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 post /api/routing/model-routers/{router_id}/status/retry
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}/status/retry:
    parameters:
      - name: router_id
        in: path
        required: true
        description: Model router id.
        schema:
          type: string
    post:
      tags:
        - Routing
      summary: Retry a model router's failed warmup
      description: >-
        Restarts one router's semantic classifier warmup when its state is
        failed. The retry runs asynchronously.
      operationId: retryModelRouterWarmup
      responses:
        '202':
          description: Warmup retry started
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Runtime status of the semantic complexity classifier and, when
                  configured, the LLM classifier. Never contains phrases,
                  embeddings, or provider secrets.
                properties:
                  state:
                    type: string
                    enum:
                      - disabled
                      - warming
                      - ready
                      - failed
                    description: >-
                      disabled = no embedding configuration; warming = reference
                      phrases are being embedded; ready = serving the current
                      configuration; failed = the desired configuration failed
                      to warm
                  loaded:
                    type: integer
                    description: Reference phrases embedded so far in the current warmup
                  total:
                    type: integer
                    description: Total reference phrases to embed in the current warmup
                  serving_previous:
                    type: boolean
                    description: >-
                      When true with state=failed, the previous generation is
                      still serving while the new one failed to warm
                  failure_reason:
                    type: string
                    enum:
                      - authentication
                      - model_unavailable
                      - rate_limited
                      - timeout
                      - provider_unavailable
                      - vector_store_unavailable
                      - invalid_response
                      - unknown
                    description: >-
                      Category of a warmup failure when state=failed. Provider
                      and backend error bodies stay in server logs; this bounded
                      vocabulary is what status clients receive.
                  error:
                    type: string
                    description: Warmup failure detail when state=failed
                  cached_phrases:
                    type: integer
                    description: >-
                      How many phrase vectors the gateway currently holds in
                      process for the configured provider and model. The cache
                      is in-process only, since vectors cannot be read back out
                      of a vector store, so a restart empties it while the saved
                      phrases look unchanged. Zero means the next save re-embeds
                      every phrase regardless of what changed.
                  storage_mode:
                    type: string
                    enum:
                      - embedded
                      - vector_store
                    description: >-
                      Where exemplar vectors are actually kept, which is not
                      always what was configured.
                      semantic.vector_store=vector_store degrades to embedded
                      whenever no top-level vector store is configured, so this
                      reports what is in force rather than what was asked for.
                      Absent until a store has been resolved.
                  namespace:
                    type: string
                    description: >-
                      The fingerprinted namespace the serving generation
                      queries, for example BifrostComplexityRouter_<hash>. The
                      backend holds no phrase text, so this is the only handle
                      on the records the classifier owns in a shared vector
                      store. Absent while nothing is serving.
                  capture_available:
                    type: boolean
                    description: >-
                      Whether there is a vector store to keep captured request
                      vectors in, for phrase suggestions. When false,
                      capture_unavailable_reason says why.
                  capture_unavailable_reason:
                    type: string
                    enum:
                      - no_vector_store
                      - embedded_vector_store
                    description: >-
                      Why requests are not captured: no_vector_store = no
                      top-level vector store is configured;
                      embedded_vector_store = the configured store is the
                      embedded one (Chromem), which capture does not use. Absent
                      when capture_available is true.
                  llm:
                    type: object
                    description: >-
                      Present on status reads, where state is disabled when no
                      llm block is configured; left out when the llm status
                      could not be read, and in the warmup retry response.
                    properties:
                      state:
                        type: string
                        enum:
                          - disabled
                          - ready
                        description: >-
                          disabled = no llm configuration; ready = the llm block
                          is configured. The classifier has no warmup, so it is
                          ready as soon as it is saved.
                  suggestion_default_instructions:
                    type: string
                    description: >-
                      The shipped phrase-suggestion instructions, served so a
                      configuration client can seed its editor and offer a
                      reset. The tier definitions and fixed output and safety
                      rules are not exposed.
                  suggestion_default_tier_instructions:
                    type: string
                    description: >-
                      The shipped tier-step instructions for suggestions, served
                      so a configuration client can seed its editor and offer a
                      reset. The tier definitions, examples and fixed output and
                      safety rules are not exposed.
                  suggestion_default_tier_prompt:
                    type: string
                    description: >-
                      Model router status only: the llm tier prompt this
                      router's suggestion runs send while it is not edited,
                      rendered from the router (its tier definitions and its own
                      phrases as examples).
                  suggestion_default_tier_criteria:
                    type: object
                    description: >-
                      Model router status only: the per-tier criteria a decision
                      tier step sends while they are not edited, rendered from
                      the router.
                    additionalProperties:
                      type: object
                      properties:
                        definition:
                          type: string
                        signals:
                          type: array
                          items:
                            type: string
                        examples:
                          type: array
                          items:
                            type: string
                  llm_default_prompt:
                    type: string
                    description: >-
                      The shipped classification guidance, served so a
                      configuration client can seed its prompt editor and offer
                      a reset without holding a copy that drifts from the
                      gateway's. Present on status reads whether or not an llm
                      block is configured; left out with llm, and in the warmup
                      retry response.
                  decision_defaults:
                    type: object
                    description: >-
                      The shipped decision-model per-tier criteria, served so a
                      configuration client can seed its editors and offer
                      resets. Filled on status reads; in the warmup retry
                      response criteria is null. The fixed question, decision
                      rule, and context rule are not exposed.
                    properties:
                      criteria:
                        type:
                          - object
                          - 'null'
                        additionalProperties:
                          type: object
                          properties:
                            definition:
                              type: string
                            signals:
                              type: array
                              items:
                                type: string
                            examples:
                              type: array
                              items:
                                type: string
        '404':
          description: The model router is not saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
        '409':
          description: The router's semantic classifier warmup is not currently failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
        '503':
          description: >-
            The model router is saved but not loaded (the message says why), or
            the routing plugin could not retry its warmup
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BifrostError'
      security:
        - ManagementBearerAuth: []
        - BasicAuth: []
components:
  schemas:
    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'
    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.