Skip to main content
PUT
Error
Required Permissions How permissions work

Authorizations

Authorization
string
header
required

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 for how permissions are derived and which endpoints are exempt.

Path Parameters

router_id
string
required

The model router; an unknown router is 404.

suggestion_id
string
required

Body

application/json
status
enum<string>
required

accepted or dismissed from open; open again from either.

Available options:
open,
accepted,
dismissed

Response

Status updated

One suggested set of phrases for a cluster of one model router's traffic.

id
string
router_id
string

The model router whose traffic the suggestion came from.

router_version
string

The router version (its phrase bank) the suggestion was computed against.

stale
boolean

True when the router now serves a different version than the one the suggestion was computed against.

status
enum<string>

open waits for the user; accepted and dismissed are the user's call and are left alone by later runs; superseded was open when a later run no longer proposed it.

Available options:
open,
accepted,
dismissed,
superseded
tier
enum<string>
Available options:
SIMPLE,
MEDIUM,
COMPLEX
phrases
string[]
category
enum<string>

Why the cluster needs phrases - no phrase matches it, it matches weakly, it routes confidently to a different tier, its routing is split, or it is one prompt template sent with different fills (its phrases are written from the template's fixed wording).

Available options:
uncovered,
weak,
misrouted,
mixed,
template
reason
string
confidence
string
request_count
integer

Requests in the cluster over the lookback window, sampled ones counted once each.

coverage
number

Share of the cluster's requests the phrases would take over routing for.

nearest_phrase
string

The live phrase closest to the cluster's centre.

nearest_tier
string
nearest_similarity
number
example_log_ids
string[]

The requests the suggestion was written from, the most central first.

current_routing
object

How the cluster's requests routed, per tier, when the suggestion's last run computed it - a snapshot from that run, not live routing; none counts those no phrase matched. Empty for a suggestion written before it was recorded.

Example:
embedding_signature
string
run_id
string

The last run that proposed it.

last_seen_at
string<date-time>
resolved_at
string<date-time>
created_at
string<date-time>
updated_at
string<date-time>