> ## 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. # Compute Warp topic clusters > Groups the indexed requests of a time window by meaning, names each group with Warp's model, and stores the result for Warp's `list_topics` tool. This is the one-time seed for an embedding model. Once it has written topics, they are kept up to date without another run: each newly indexed request is filed under its topic, requests that match none are pooled and clustered into new topics once `topic_discovery_min_requests` of them are waiting, and an hourly pass retires topics that went quiet and merges ones that came to mean the same thing. A second run for the same model is refused with 409. Changing the embedding model starts over with no topics, and so does upkeep retiring every topic. A run that finds no indexed requests in the window completes without writing any, so the model can still be seeded with another window. One run reads every indexed request in the window. Up to 20,000 of them, drawn from across the window, are clustered into topics, and the rest are filed under their nearest topic as they are read (`assigned` in the status). Administrators only: the local admin in OSS, `Warp` Update in enterprise. ## OpenAPI ````yaml /openapi/openapi.json post /api/warp/log-index/topics openapi: 3.1.0 info: title: Bifrost API description: > Bifrost HTTP Transport API for AI model inference and gateway management. This API provides a unified interface for interacting with multiple AI providers including OpenAI, Anthropic, Bedrock, Gemini, and more through a single API, along with comprehensive management APIs for configuring and monitoring the gateway. ## API Structure ### Unified Inference API (`/v1/*`) The primary API using Bifrost's unified format. Model parameters use the format `provider/model` (e.g., `openai/gpt-4`, `anthropic/claude-3-opus`). ### Async Inference API (`/v1/async/*`) Submit inference requests for asynchronous execution. Returns a job ID immediately and allows polling for results. Supports all inference types except batches, files, and containers. ### Provider Integration APIs Native provider-format APIs for drop-in compatibility: - `/openai/*` - OpenAI-compatible API - `/anthropic/*` - Anthropic-compatible API - `/genai/*` - Google GenAI (Gemini) compatible API - `/bedrock/*` - AWS Bedrock compatible API - `/cohere/*` - Cohere compatible API ### Framework Integration APIs Multi-provider proxy endpoints for AI frameworks: - `/litellm/*` - LiteLLM proxy with all provider formats - `/langchain/*` - LangChain compatible endpoints - `/pydanticai/*` - PydanticAI compatible endpoints ### Management APIs (`/api/*`) APIs for managing and monitoring the Bifrost gateway: - `/api/config` - Configuration management - `/api/providers` - Provider and API key management - `/api/plugins` - Plugin management - `/api/governance/*` - Virtual keys, teams, customers, budgets, rate limits, routing rules, and pricing overrides - `/api/logs` - Log search and analytics - `/api/mcp/*` - MCP (Model Context Protocol) client management - `/api/session/*` - Authentication and session management - `/api/cache/*` - Cache management - `/health` - Health check endpoint ## Fallbacks Requests can include fallback models that will be tried if the primary model fails. version: 1.0.0 contact: name: Contact Us url: https://getmaxim.ai/bifrost license: name: Apache 2.0 url: https://opensource.org/licenses/Apache-2.0 servers: - url: '{baseUrl}' description: Your Bifrost instance variables: baseUrl: default: http://localhost:8080 description: Base URL of your Bifrost instance (e.g. https://bifrost.mycompany.com) security: - BearerAuth: [] - BasicAuth: [] - ApiKeyAuth: [] tags: - name: Agent Gateway description: >- Agent registrations, A2A protocol calls, push callbacks, and operation history - name: Models description: Model listing and information - name: Chat Completions description: Chat-based text generation - name: Text Completions description: Text completion generation - name: Responses description: OpenAI Responses API compatible endpoints - name: OCR description: Optical character recognition for documents and images - name: Rerank description: Document reranking by relevance to a query - name: Decisions description: Structured decisions evaluated against annotated function-tool definitions - name: Embeddings description: Text embedding generation - name: Images description: Image generations, editing, and variations - name: Videos description: Video generation and management - name: Audio description: Speech synthesis and transcription - name: Count Tokens description: Token counting utilities - name: Batch description: Batch processing operations - name: Files description: File management operations - name: Containers description: Container management operations - name: Async Jobs description: Asynchronous job submission and retrieval endpoints - name: Realtime description: Realtime WebSocket and WebRTC endpoints - name: OpenAI Integration description: OpenAI-compatible API endpoints (/openai/*) - name: Azure Integration description: Azure OpenAI integration endpoints - name: Anthropic Integration description: Anthropic-compatible API endpoints (/anthropic/*) - name: GenAI Integration description: Google GenAI (Gemini) compatible API endpoints (/genai/*) - name: Bedrock Integration description: AWS Bedrock compatible API endpoints (/bedrock/*) - name: Cohere Integration description: Cohere compatible API endpoints (/cohere/*) - name: Typesafe Integration description: Typesafe compatible API endpoints (/typesafe/*) - name: LiteLLM Integration description: LiteLLM proxy endpoints with multi-provider support (/litellm/*) - name: LangChain Integration description: LangChain compatible endpoints with multi-provider support (/langchain/*) - name: PydanticAI Integration description: >- PydanticAI compatible endpoints with multi-provider support (/pydanticai/*) - name: Health description: Health check endpoints - name: Configuration description: Configuration management endpoints - name: Session description: Session and authentication endpoints - name: Providers description: Provider management endpoints - name: Plugins description: Plugin management endpoints - name: MCP description: Model Context Protocol endpoints - name: Governance description: Virtual keys, teams, and customers management - name: Routing description: Routing rules and complexity analyzer configuration - name: Logging description: Log search and management endpoints - name: Cache description: Cache management endpoints - name: Vault description: Vault secret management endpoints - name: Skills description: Skills Repository management, marketplace, and download endpoints - name: Audit Logs description: >- CADF-compliant audit log search, export, and signature verification endpoints - name: Webhooks description: Webhook endpoint management and signed async-job delivery history - name: Notifications description: >- Role-targeted dashboard notifications, delivered over the dashboard WebSocket - name: News Feeds description: >- RSS and Atom news sources shown in the News tab of the dashboard notification tray - name: Background Jobs description: >- Status, progress and cancellation of durable background jobs (cost recalculation, Warp log indexing, and others) - name: Warp description: >- Configuration for Warp, the dashboard agent that answers questions about the deployment's own telemetry - name: Relays description: >- Relays to non-LLM HTTP APIs - endpoint management, usage preview, Relay Logs and the /relay data plane paths: /api/warp/log-index/topics: post: tags: - Warp summary: Compute Warp topic clusters description: > Groups the indexed requests of a time window by meaning, names each group with Warp's model, and stores the result for Warp's `list_topics` tool. This is the one-time seed for an embedding model. Once it has written topics, they are kept up to date without another run: each newly indexed request is filed under its topic, requests that match none are pooled and clustered into new topics once `topic_discovery_min_requests` of them are waiting, and an hourly pass retires topics that went quiet and merges ones that came to mean the same thing. A second run for the same model is refused with 409. Changing the embedding model starts over with no topics, and so does upkeep retiring every topic. A run that finds no indexed requests in the window completes without writing any, so the model can still be seeded with another window. One run reads every indexed request in the window. Up to 20,000 of them, drawn from across the window, are clustered into topics, and the rest are filed under their nearest topic as they are read (`assigned` in the status). Administrators only: the local admin in OSS, `Warp` Update in enterprise. operationId: startWarpTopicClustering requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WarpTopicsRequest' responses: '202': description: Topic clustering accepted content: application/json: schema: $ref: '#/components/schemas/WarpTopicsStatus' '400': description: | The request body is malformed JSON, `start_time` or `end_time` is missing or not an RFC3339 timestamp, or the time range is invalid - `end_time` must be after `start_time`. content: application/json: schema: $ref: '#/components/schemas/BifrostError' '403': description: >- Caller is not the local admin (OSS) and lacks `Warp` Update (enterprise) '409': description: > A topic clustering run, or a discovery of new topics, is already active, and the body is that job, so a client can show its progress instead of reporting a bare conflict. Or the configured embedding model already has topics, which keep themselves up to date, and the body is an error saying so. content: application/json: schema: oneOf: - $ref: '#/components/schemas/WarpTopicsStatus' - $ref: '#/components/schemas/BifrostError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/BifrostError' '503': description: > The background job runner or the job store is unavailable, or Warp itself cannot prepare the job - no usable configuration (including no embedding provider or model; topics are computed in the embedding space the logs were indexed with, so a run cannot start without one), or no vector store to read from. security: - ManagementBearerAuth: [] components: schemas: WarpTopicsRequest: type: object properties: start_time: type: string format: date-time end_time: type: string format: date-time required: - start_time - end_time WarpTopicsStatus: type: object description: | A topic clustering job. It shares the backfill's counters, which mean something different here: see each field. properties: id: type: string status: type: string enum: - idle - pending - running - cancelling - completed - failed - cancelled start_time: type: string format: date-time end_time: type: string format: date-time total: type: integer format: int64 description: Requests read from the window so far. Equal to `scanned`. scanned: type: integer format: int64 description: Requests read from the window. Every model call is one request. indexed: type: integer format: int64 description: Topics written. skipped: type: integer format: int64 description: > Requests that were indexed but are no longer in the log store, so they were clustered but could not be filed under a topic. failed: type: integer format: int64 description: | Topics whose name fell back to their most common words because the model could not be reached. clustered: type: integer format: int64 description: Requests that were clustered. assigned: type: integer format: int64 description: > Requests given to the nearest topic after clustering stopped. Omitted when a run clustered everything it read. unassigned: type: integer format: int64 description: Requests that ended in no topic. capped: type: boolean description: | Set when a run stopped at a read limit before the end of the window. Runs read the whole window, so this is not set. merged: type: integer format: int64 description: Clusters folded into another for being near-duplicates. merged_by_name: type: integer format: int64 description: Clusters joined after naming because they were given the same name. themes: type: integer format: int64 description: | How many themes the active topics were grouped into once the run had written its topics. Omitted when there were too few topics to group, or the grouping could not run (see last_error). merge_threshold: type: number format: double description: | The similarity at or above which two clusters were merged, derived from the run's own clusters. Omitted when the run had nothing to derive one from. topics: type: array description: The topics the run wrote, in the order they were written. items: $ref: '#/components/schemas/WarpTopicSummary' last_error: type: string message: type: string created_at: type: string format: date-time started_at: type: string format: date-time completed_at: type: string format: date-time required: - status - total - scanned - indexed - skipped - failed 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' WarpTopicSummary: type: object properties: label: type: string description: The topic's name. size: type: integer format: int64 description: Requests in the topic. cohesion: type: number format: double description: | How alike the topic's requests are, from 0 to 1: their average similarity to the topic's centre. required: - label - size - cohesion ErrorField: type: object properties: type: type: string code: type: string message: type: string param: type: string event_id: type: string BifrostErrorExtraFields: type: object properties: routing_info: $ref: '#/components/schemas/RoutingInfo' provider: $ref: '#/components/schemas/ModelProvider' deprecated: true description: 'Deprecated: use routing_info.provider.' original_model_requested: type: string deprecated: true description: >- Deprecated: use routing_info.primary_model when routing_info.is_fallback is true, otherwise routing_info.model. For the model the caller asked for, read routing_info.requested_model. resolved_model_used: type: string deprecated: true description: >- Deprecated: use routing_info.resolved_key_alias.model_id when an alias matched, otherwise routing_info.model. request_type: type: string mcp_request_type: type: string a2a_request_type: type: string description: Agent Gateway operation, for A2A errors a2a_agent_name: type: string error_type: type: string description: >- Normalized, low-cardinality classification of why the request failed, declared by whichever component refused it. Prefixed by fault domain (caller_, policy_, provider_, bifrost_). Absent on failures that were not classified at source. retry_after_ms: type: integer format: int64 minimum: 1000 maximum: 300000 description: >- The provider's hint for how long to wait before retrying, in milliseconds, read from its retry-after-ms or Retry-After header or its google.rpc.RetryInfo error detail, and clamped to between 1000 and 300000. Absent when the provider gave no explicit hint. raw_request: description: Raw provider request, when raw request capture is enabled raw_response: description: Raw provider response, when raw response capture is enabled converted_request_type: type: string dropped_compat_plugin_params: type: array items: type: string latency: type: integer format: int64 description: Latency in milliseconds key_statuses: type: array description: >- Per-key results, for requests that ran on every key such as listing models items: type: object properties: key_id: type: string status: type: string enum: - success - list_models_failed provider: $ref: '#/components/schemas/ModelProvider' error: $ref: '#/components/schemas/BifrostError' mcp_auth_required: type: object description: >- Set when a per-user MCP tool needs the caller to complete an inline auth flow properties: kind: type: string mcp_client_id: type: string mcp_client_name: type: string message: type: string authorize_url: type: string session_id: type: string subject_token_missing: type: boolean description: >- token_exchange only. True when there was nothing to exchange, including when the caller's Bifrost sign-in has expired; message says which exchange_error: type: string description: >- token_exchange only. The identity provider's error code and description when it refused the exchange billed_usage: $ref: '#/components/schemas/BifrostLLMUsage' description: >- Usage the provider reported and billed even though the request failed RoutingInfo: type: object description: >- Which provider, model and key handled the attempt that produced this response or error, and what the caller asked for. Also sent as x-bifrost-routing-info-* response headers. properties: provider: $ref: '#/components/schemas/ModelProvider' description: Provider that ran the attempt model: type: string description: Model sent to that provider key: type: string description: Name of the stored key used, never its ID or secret resolved_key_alias: $ref: '#/components/schemas/ResolvedKeyAlias' is_fallback: type: boolean description: >- True when a fallback served the request or returned the error. Omitted when false. primary_provider: $ref: '#/components/schemas/ModelProvider' description: The primary attempt's provider. Set only when a fallback ran. primary_model: type: string description: The primary attempt's model. Set only when a fallback ran. requested_provider: $ref: '#/components/schemas/ModelProvider' description: >- Provider the caller asked for, before routing rules, load balancing or session affinity changed it. Omitted when the caller sent a bare model. requested_model: type: string description: Model the caller asked for, before anything changed it server_side_fallback_model: type: string description: Model that answered when Anthropic switched models inside one call ModelProvider: type: string description: AI model provider identifier enum: - anthropic - azure - bedrock - bedrock_mantle - sagemaker - cerebras - cohere - deepseek - gemini - groq - mistral - ollama - opencode-go - opencode-zen - openai - parasail - perplexity - sgl - vertex - openrouter - elevenlabs - huggingface - nebius - xai - replicate - vllm - runway - runware - fireworks - sarvam - wafer - databricks - cloudflare - typesafe - minimax - byteplus BifrostLLMUsage: type: object description: Token usage information properties: prompt_tokens: type: integer description: > Total input tokens including any prompt-cache tokens (read + write). Subtract prompt_tokens_details.cached_read_tokens and prompt_tokens_details.cached_write_tokens to get the non-cached portion. prompt_tokens_details: $ref: '#/components/schemas/ChatPromptTokensDetails' completion_tokens: type: integer description: Number of output/completion tokens generated. completion_tokens_details: $ref: '#/components/schemas/ChatCompletionTokensDetails' total_tokens: type: integer tool_usage: type: object description: | Counts of provider-hosted (server-side) tool calls billed per call. properties: web_search: type: object properties: num_requests: type: integer description: Number of billable web search calls. cost: $ref: '#/components/schemas/BifrostCost' ResolvedKeyAlias: type: object description: Set only when the requested model matched a model alias on the key required: - model_id properties: model_id: type: string description: Model ID sent to the provider model_name: type: string description: Canonical model name, used for pricing and logs model_family: type: string description: Resolved model family ChatPromptTokensDetails: type: object properties: text_tokens: type: integer audio_tokens: type: integer image_tokens: type: integer cached_read_tokens: type: integer description: > Tokens served from the prompt cache (cache hit). These tokens are already included in prompt_tokens and are billed at the reduced cache-read rate. Populated for all providers that support prompt caching (Anthropic, Bedrock, OpenAI, Gemini, xAI, etc.). cached_write_tokens: type: integer description: > Tokens written to the prompt cache on this request (cache creation / write). These tokens are already included in prompt_tokens and are billed at the cache-creation rate. Populated for providers that separately report cache write tokens (Anthropic, Bedrock). ChatCompletionTokensDetails: type: object properties: text_tokens: type: integer accepted_prediction_tokens: type: integer audio_tokens: type: integer citation_tokens: type: integer num_search_queries: type: integer deprecated: true description: >- Deprecated, use tool_usage.web_search.num_requests. Will be removed in 3.0.0. reasoning_tokens: type: integer image_tokens: type: integer rejected_prediction_tokens: type: integer BifrostCost: type: object description: Cost breakdown for the request properties: input_tokens_cost: type: number output_tokens_cost: type: number reasoning_tokens_cost: type: number description: Cost for reasoning/thinking tokens (reasoning models) citation_tokens_cost: type: number description: Cost for citation tokens search_queries_cost: type: number description: Cost for web search queries request_cost: type: number total_cost: type: number securitySchemes: BearerAuth: type: http scheme: bearer description: > Bearer token authentication. Use your provider API key or Bifrost authentication token. Virtual keys (prefixed with `sk-bf-`) can also be passed here. BasicAuth: type: http scheme: basic description: > Basic authentication using the Bifrost admin username and password (`auth_config.admin_username` / `auth_config.admin_password`). Accepted on management APIs (`/api/*`, `/metrics`, `/ws`) only - the inference middleware never validates Basic credentials. ApiKeyAuth: type: apiKey in: header name: x-api-key description: | API key authentication via the `x-api-key` header. Virtual keys (prefixed with `sk-bf-`) can also be passed here. ManagementBearerAuth: type: http scheme: bearer description: > Management API authentication for `/api/*` endpoints. Use the `Authorization` header with `Bearer `, where `` is one of: - a Bifrost management API key, - a dashboard session token issued by `POST /api/session/login`, - base64 of `:` (legacy equivalent of `BasicAuth`). Virtual keys (`sk-bf-*`) and the `x-api-key` header are not accepted on management APIs - the sole exception is `GET /api/governance/virtual-keys/quota`, which is virtual-key-only. Authentication alone is not sufficient in Bifrost Enterprise: each operation page shows a **Required Permissions** table (`Resource:Operation`, for example `Dashboard:View`) above its Authorizations section, and the caller's RBAC role or management API key scopes must include what it lists, otherwise the request is rejected with `403 Forbidden`. A local admin — authenticated with the admin password, or any caller on a deployment with dashboard auth disabled — bypasses these checks and can call every management endpoint. **OSS setup lock.** On Bifrost OSS, while dashboard auth is not active (no admin account, or auth disabled), every management endpoint except the public ones (`/health`, `/api/version`, `/api/session/is-auth-enabled`, `/api/session/login`, ...) requires the operator's setup token in the `X-Bifrost-Setup-Token` header, in place of `Authorization`. The token is set with `setup_token` in `config.json` or the `BIFROST_SETUP_TOKEN` environment variable. A missing header returns `401`, a wrong token `403`. The header stops working once dashboard auth is enabled. The dashboard instead trades the token once for an HttpOnly `bifrost_setup_session` cookie via `POST /api/session/setup`. See [Required permissions](/api/procuring-api-keys#required-permissions) for how permissions are derived and which endpoints are exempt. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.