A valid request URL is required to generate request examples{
"history_retention_days": 7,
"snapshot_persist_interval_seconds": 300,
"direction_selection_enabled": true,
"route_selection_enabled": true,
"append_fallbacks_to_pinned": true,
"reroute_failed_directions": true,
"reroute_target": "pool",
"prune_failed_fallbacks": true,
"history_enabled": true
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"routing_info": {
"provider": "anthropic",
"model": "<string>",
"key": "<string>",
"resolved_key_alias": {
"model_id": "<string>",
"model_name": "<string>",
"model_family": "<string>"
},
"is_fallback": true,
"primary_provider": "anthropic",
"primary_model": "<string>",
"requested_provider": "anthropic",
"requested_model": "<string>",
"server_side_fallback_model": "<string>"
},
"provider": "anthropic",
"original_model_requested": "<string>",
"resolved_model_used": "<string>",
"request_type": "<string>",
"mcp_request_type": "<string>",
"a2a_request_type": "<string>",
"a2a_agent_name": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500,
"raw_request": "<unknown>",
"raw_response": "<unknown>",
"converted_request_type": "<string>",
"dropped_compat_plugin_params": [
"<string>"
],
"latency": 123,
"key_statuses": [
{
"key_id": "<string>",
"status": "success",
"provider": "anthropic",
"error": "<unknown>"
}
],
"mcp_auth_required": {
"kind": "<string>",
"mcp_client_id": "<string>",
"mcp_client_name": "<string>",
"message": "<string>",
"authorize_url": "<string>",
"session_id": "<string>"
},
"billed_usage": {
"prompt_tokens": 123,
"prompt_tokens_details": {
"text_tokens": 123,
"audio_tokens": 123,
"image_tokens": 123,
"cached_read_tokens": 123,
"cached_write_tokens": 123
},
"completion_tokens": 123,
"completion_tokens_details": {
"text_tokens": 123,
"accepted_prediction_tokens": 123,
"audio_tokens": 123,
"citation_tokens": 123,
"num_search_queries": 123,
"reasoning_tokens": 123,
"image_tokens": 123,
"rejected_prediction_tokens": 123
},
"total_tokens": 123,
"tool_usage": {
"web_search": {
"num_requests": 123
}
},
"cost": {
"input_tokens_cost": 123,
"output_tokens_cost": 123,
"reasoning_tokens_cost": 123,
"citation_tokens_cost": 123,
"search_queries_cost": 123,
"request_cost": 123,
"total_cost": 123
}
}
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"routing_info": {
"provider": "anthropic",
"model": "<string>",
"key": "<string>",
"resolved_key_alias": {
"model_id": "<string>",
"model_name": "<string>",
"model_family": "<string>"
},
"is_fallback": true,
"primary_provider": "anthropic",
"primary_model": "<string>",
"requested_provider": "anthropic",
"requested_model": "<string>",
"server_side_fallback_model": "<string>"
},
"provider": "anthropic",
"original_model_requested": "<string>",
"resolved_model_used": "<string>",
"request_type": "<string>",
"mcp_request_type": "<string>",
"a2a_request_type": "<string>",
"a2a_agent_name": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500,
"raw_request": "<unknown>",
"raw_response": "<unknown>",
"converted_request_type": "<string>",
"dropped_compat_plugin_params": [
"<string>"
],
"latency": 123,
"key_statuses": [
{
"key_id": "<string>",
"status": "success",
"provider": "anthropic",
"error": "<unknown>"
}
],
"mcp_auth_required": {
"kind": "<string>",
"mcp_client_id": "<string>",
"mcp_client_name": "<string>",
"message": "<string>",
"authorize_url": "<string>",
"session_id": "<string>"
},
"billed_usage": {
"prompt_tokens": 123,
"prompt_tokens_details": {
"text_tokens": 123,
"audio_tokens": 123,
"image_tokens": 123,
"cached_read_tokens": 123,
"cached_write_tokens": 123
},
"completion_tokens": 123,
"completion_tokens_details": {
"text_tokens": 123,
"accepted_prediction_tokens": 123,
"audio_tokens": 123,
"citation_tokens": 123,
"num_search_queries": 123,
"reasoning_tokens": 123,
"image_tokens": 123,
"rejected_prediction_tokens": 123
},
"total_tokens": 123,
"tool_usage": {
"web_search": {
"num_requests": 123
}
},
"cost": {
"input_tokens_cost": 123,
"output_tokens_cost": 123,
"reasoning_tokens_cost": 123,
"citation_tokens_cost": 123,
"search_queries_cost": 123,
"request_cost": 123,
"total_cost": 123
}
}
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"routing_info": {
"provider": "anthropic",
"model": "<string>",
"key": "<string>",
"resolved_key_alias": {
"model_id": "<string>",
"model_name": "<string>",
"model_family": "<string>"
},
"is_fallback": true,
"primary_provider": "anthropic",
"primary_model": "<string>",
"requested_provider": "anthropic",
"requested_model": "<string>",
"server_side_fallback_model": "<string>"
},
"provider": "anthropic",
"original_model_requested": "<string>",
"resolved_model_used": "<string>",
"request_type": "<string>",
"mcp_request_type": "<string>",
"a2a_request_type": "<string>",
"a2a_agent_name": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500,
"raw_request": "<unknown>",
"raw_response": "<unknown>",
"converted_request_type": "<string>",
"dropped_compat_plugin_params": [
"<string>"
],
"latency": 123,
"key_statuses": [
{
"key_id": "<string>",
"status": "success",
"provider": "anthropic",
"error": "<unknown>"
}
],
"mcp_auth_required": {
"kind": "<string>",
"mcp_client_id": "<string>",
"mcp_client_name": "<string>",
"message": "<string>",
"authorize_url": "<string>",
"session_id": "<string>"
},
"billed_usage": {
"prompt_tokens": 123,
"prompt_tokens_details": {
"text_tokens": 123,
"audio_tokens": 123,
"image_tokens": 123,
"cached_read_tokens": 123,
"cached_write_tokens": 123
},
"completion_tokens": 123,
"completion_tokens_details": {
"text_tokens": 123,
"accepted_prediction_tokens": 123,
"audio_tokens": 123,
"citation_tokens": 123,
"num_search_queries": 123,
"reasoning_tokens": 123,
"image_tokens": 123,
"rejected_prediction_tokens": 123
},
"total_tokens": 123,
"tool_usage": {
"web_search": {
"num_requests": 123
}
},
"cost": {
"input_tokens_cost": 123,
"output_tokens_cost": 123,
"reasoning_tokens_cost": 123,
"citation_tokens_cost": 123,
"search_queries_cost": 123,
"request_cost": 123,
"total_cost": 123
}
}
}
}Update adaptive routing settings
Replaces every adaptive routing setting and applies the change on every node in the cluster.
A switch left out of the body is turned off, so read the settings first and send them all
back with your change. history_retention_days applies from the next restart; every other
setting applies at once.
Returns 400 when the body is not valid JSON, when snapshot_persist_interval_seconds is
missing or outside 5 to 86400, when history_retention_days is missing or outside 1 to 30,
or when reroute_target is any value other than pool or fallbacks; an omitted or empty
reroute_target is stored as pool.
A valid request URL is required to generate request examples{
"history_retention_days": 7,
"snapshot_persist_interval_seconds": 300,
"direction_selection_enabled": true,
"route_selection_enabled": true,
"append_fallbacks_to_pinned": true,
"reroute_failed_directions": true,
"reroute_target": "pool",
"prune_failed_fallbacks": true,
"history_enabled": true
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"routing_info": {
"provider": "anthropic",
"model": "<string>",
"key": "<string>",
"resolved_key_alias": {
"model_id": "<string>",
"model_name": "<string>",
"model_family": "<string>"
},
"is_fallback": true,
"primary_provider": "anthropic",
"primary_model": "<string>",
"requested_provider": "anthropic",
"requested_model": "<string>",
"server_side_fallback_model": "<string>"
},
"provider": "anthropic",
"original_model_requested": "<string>",
"resolved_model_used": "<string>",
"request_type": "<string>",
"mcp_request_type": "<string>",
"a2a_request_type": "<string>",
"a2a_agent_name": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500,
"raw_request": "<unknown>",
"raw_response": "<unknown>",
"converted_request_type": "<string>",
"dropped_compat_plugin_params": [
"<string>"
],
"latency": 123,
"key_statuses": [
{
"key_id": "<string>",
"status": "success",
"provider": "anthropic",
"error": "<unknown>"
}
],
"mcp_auth_required": {
"kind": "<string>",
"mcp_client_id": "<string>",
"mcp_client_name": "<string>",
"message": "<string>",
"authorize_url": "<string>",
"session_id": "<string>"
},
"billed_usage": {
"prompt_tokens": 123,
"prompt_tokens_details": {
"text_tokens": 123,
"audio_tokens": 123,
"image_tokens": 123,
"cached_read_tokens": 123,
"cached_write_tokens": 123
},
"completion_tokens": 123,
"completion_tokens_details": {
"text_tokens": 123,
"accepted_prediction_tokens": 123,
"audio_tokens": 123,
"citation_tokens": 123,
"num_search_queries": 123,
"reasoning_tokens": 123,
"image_tokens": 123,
"rejected_prediction_tokens": 123
},
"total_tokens": 123,
"tool_usage": {
"web_search": {
"num_requests": 123
}
},
"cost": {
"input_tokens_cost": 123,
"output_tokens_cost": 123,
"reasoning_tokens_cost": 123,
"citation_tokens_cost": 123,
"search_queries_cost": 123,
"request_cost": 123,
"total_cost": 123
}
}
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"routing_info": {
"provider": "anthropic",
"model": "<string>",
"key": "<string>",
"resolved_key_alias": {
"model_id": "<string>",
"model_name": "<string>",
"model_family": "<string>"
},
"is_fallback": true,
"primary_provider": "anthropic",
"primary_model": "<string>",
"requested_provider": "anthropic",
"requested_model": "<string>",
"server_side_fallback_model": "<string>"
},
"provider": "anthropic",
"original_model_requested": "<string>",
"resolved_model_used": "<string>",
"request_type": "<string>",
"mcp_request_type": "<string>",
"a2a_request_type": "<string>",
"a2a_agent_name": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500,
"raw_request": "<unknown>",
"raw_response": "<unknown>",
"converted_request_type": "<string>",
"dropped_compat_plugin_params": [
"<string>"
],
"latency": 123,
"key_statuses": [
{
"key_id": "<string>",
"status": "success",
"provider": "anthropic",
"error": "<unknown>"
}
],
"mcp_auth_required": {
"kind": "<string>",
"mcp_client_id": "<string>",
"mcp_client_name": "<string>",
"message": "<string>",
"authorize_url": "<string>",
"session_id": "<string>"
},
"billed_usage": {
"prompt_tokens": 123,
"prompt_tokens_details": {
"text_tokens": 123,
"audio_tokens": 123,
"image_tokens": 123,
"cached_read_tokens": 123,
"cached_write_tokens": 123
},
"completion_tokens": 123,
"completion_tokens_details": {
"text_tokens": 123,
"accepted_prediction_tokens": 123,
"audio_tokens": 123,
"citation_tokens": 123,
"num_search_queries": 123,
"reasoning_tokens": 123,
"image_tokens": 123,
"rejected_prediction_tokens": 123
},
"total_tokens": 123,
"tool_usage": {
"web_search": {
"num_requests": 123
}
},
"cost": {
"input_tokens_cost": 123,
"output_tokens_cost": 123,
"reasoning_tokens_cost": 123,
"citation_tokens_cost": 123,
"search_queries_cost": 123,
"request_cost": 123,
"total_cost": 123
}
}
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"routing_info": {
"provider": "anthropic",
"model": "<string>",
"key": "<string>",
"resolved_key_alias": {
"model_id": "<string>",
"model_name": "<string>",
"model_family": "<string>"
},
"is_fallback": true,
"primary_provider": "anthropic",
"primary_model": "<string>",
"requested_provider": "anthropic",
"requested_model": "<string>",
"server_side_fallback_model": "<string>"
},
"provider": "anthropic",
"original_model_requested": "<string>",
"resolved_model_used": "<string>",
"request_type": "<string>",
"mcp_request_type": "<string>",
"a2a_request_type": "<string>",
"a2a_agent_name": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500,
"raw_request": "<unknown>",
"raw_response": "<unknown>",
"converted_request_type": "<string>",
"dropped_compat_plugin_params": [
"<string>"
],
"latency": 123,
"key_statuses": [
{
"key_id": "<string>",
"status": "success",
"provider": "anthropic",
"error": "<unknown>"
}
],
"mcp_auth_required": {
"kind": "<string>",
"mcp_client_id": "<string>",
"mcp_client_name": "<string>",
"message": "<string>",
"authorize_url": "<string>",
"session_id": "<string>"
},
"billed_usage": {
"prompt_tokens": 123,
"prompt_tokens_details": {
"text_tokens": 123,
"audio_tokens": 123,
"image_tokens": 123,
"cached_read_tokens": 123,
"cached_write_tokens": 123
},
"completion_tokens": 123,
"completion_tokens_details": {
"text_tokens": 123,
"accepted_prediction_tokens": 123,
"audio_tokens": 123,
"citation_tokens": 123,
"num_search_queries": 123,
"reasoning_tokens": 123,
"image_tokens": 123,
"rejected_prediction_tokens": 123
},
"total_tokens": 123,
"tool_usage": {
"web_search": {
"num_requests": 123
}
},
"cost": {
"input_tokens_cost": 123,
"output_tokens_cost": 123,
"reasoning_tokens_cost": 123,
"citation_tokens_cost": 123,
"search_queries_cost": 123,
"request_cost": 123,
"total_cost": 123
}
}
}
}| Permission | Granted via |
|---|---|
AdaptiveRouter:Update | RBAC role or API key scope |
Authorizations
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 ofBasicAuth).
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 for how
permissions are derived and which endpoints are exempt.
Body
The adaptive routing settings. On PUT this is a full replacement: a switch left out of the
body is turned off, and history_retention_days and snapshot_persist_interval_seconds must
be sent. Unknown fields are ignored.
Days routing history is kept. A change applies from the next restart. Outside 1 to 30, or omitted, is rejected with 400.
1 <= x <= 30How often routing state is saved, in seconds. Outside 5 to 86400, or omitted, is rejected with 400.
5 <= x <= 86400Adaptive provider selection. Reads true on a fresh install.
Adaptive key selection. Reads true on a fresh install.
Add healthy fallbacks to requests that already name a provider. Reads false on a fresh install.
Redirect requests that name a failing provider. Reads false on a fresh install.
Where a redirected request goes. pool picks among the eligible providers adaptive routing
scores; fallbacks takes the request's first configured fallback that is not failing.
An omitted or empty value is stored as pool. Any other value is rejected with 400.
pool, fallbacks Skip failing providers in a request's configured fallbacks. Reads false on a fresh install.
Record routing history. Reads true on a fresh install.
Response
Settings saved and applied. Returns the saved settings, with an omitted reroute_target stored as pool.
The adaptive routing settings. On PUT this is a full replacement: a switch left out of the
body is turned off, and history_retention_days and snapshot_persist_interval_seconds must
be sent. Unknown fields are ignored.
Days routing history is kept. A change applies from the next restart. Outside 1 to 30, or omitted, is rejected with 400.
1 <= x <= 30How often routing state is saved, in seconds. Outside 5 to 86400, or omitted, is rejected with 400.
5 <= x <= 86400Adaptive provider selection. Reads true on a fresh install.
Adaptive key selection. Reads true on a fresh install.
Add healthy fallbacks to requests that already name a provider. Reads false on a fresh install.
Redirect requests that name a failing provider. Reads false on a fresh install.
Where a redirected request goes. pool picks among the eligible providers adaptive routing
scores; fallbacks takes the request's first configured fallback that is not failing.
An omitted or empty value is stored as pool. Any other value is rejected with 400.
pool, fallbacks Skip failing providers in a request's configured fallbacks. Reads false on a fresh install.
Record routing history. Reads true on a fresh install.
Was this page helpful?