Update Warp configuration

Writes Warp’s settings. Administrators only.

A single write points the server at a provider key and a model it will then call on its own behalf, which is not something an ordinary dashboard user should be able to do. In OSS only the local admin may write; in enterprise the caller needs Warp Update. Anyone else gets 403. The response carries the key reference back, not a redacted credential - there is no secret stored here to redact.

api_key_id is a reference, not a credential, so it round-trips in the clear and needs no omitted-versus-empty rule: omitting it writes an empty value and clears the stored reference.

provider and model are Warp’s default model. additional_models lists the others a chat request may name, so this write is also what decides which models dashboard users can switch between: they pick among what is stored here and cannot add to it.

PUT /api/warp/config

Error

A valid request URL is required to generate request examples

200

{
  "configured": true,
  "enabled": true,
  "provider": "openai",
  "model": "gpt-4o",
  "max_iterations": 8,
  "request_timeout_seconds": 120,
  "history_retention_days": 30,
  "embedding_provider": "openai",
  "embedding_model": "text-embedding-3-small",
  "embedding_dimension": 1536,
  "log_vector_store_namespace": "BifrostWarpLogs",
  "semantic_search_threshold": 0.8,
  "semantic_search_limit": 10,
  "vector_store_connected": true,
  "api_key_id": "<string>",
  "additional_models": [
    {
      "provider": "anthropic",
      "model": "claude-sonnet-5",
      "api_key_id": "<string>"
    }
  ],
  "system_prompt_suffix": "<string>",
  "embedding_api_key_id": "<string>"
}

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.

Body

application/json

The write body. Only a config that claims to be usable has to be complete: when enabled is false, provider and model may be empty, so an operator can fill the form in over more than one sitting.

Switching enabled on is what makes the rest required - see the conditional below, which mirrors what the server enforces so a generated client learns the rule from the schema rather than from a rejected request.

enabled · boolean · default: false

provider · string

Required when enabled is true, and must name a provider registered in this Bifrost deployment - the built-in providers plus any custom ones it has registered. There is deliberately no fixed enum: the registry is per-deployment, so an enum would reject valid custom provider names. An unregistered name is rejected with 400.

Example:

"openai"

model · string

Required when enabled is true.

Example:

"gpt-4o"

api_key_id · string

Which of the provider's configured keys Warp should use. Empty is valid and common: a provider on a trusted network, or one using ambient IAM credentials, needs no key at all.

additional_models · object[]

The models to expose beside the default (provider and model above). Replaced whole on every write, like the default itself: leaving the field out clears the list.

Every entry must be complete whether or not enabled is true, must name a registered provider, and must not repeat the provider and model of the default or of another entry. Any of those is rejected with 400.

Maximum array length: 20

Show child attributes

max_iterations · integer

Zero means "use the default".

Required range: 0 <= x <= 20

request_timeout_seconds · integer

Zero means "use the default".

Required range: x >= 0

history_retention_days · integer

How long a saved chat is kept after its last turn. Zero means "use the default"; there is no maximum, because the per-owner conversation cap already bounds the table and how long a transcript stays readable is a policy question with no technically correct ceiling.

Required range: x >= 0

system_prompt_suffix · string

embedding_provider · string

Required when enabled is true.

embedding_model · string

Required when enabled is true.

embedding_api_key_id · string

embedding_dimension · integer

Must be positive when enabled is true.

Required range: x >= 0

log_vector_store_namespace · string · default: BifrostWarpLogs

semantic_search_threshold · number · default: 0.8

Zero means "use the default". ValidateConfigInput resolves an explicit zero before validating, so the write is accepted; the resolved value on WarpConfig keeps the positive bound.

Required range: 0 <= x <= 1

semantic_search_limit · integer · default: 10

Zero means "use the default", resolved before validation.

Required range: 0 <= x <= 25

Response

200

application/json

The updated configuration

Warp's deployment-wide settings, as returned by the read API.

The stored provider credential is never included. api_key_id names which of the provider's configured keys Warp uses - a reference, not a secret, so the settings form can render "configured" without the key itself ever leaving the server: a dashboard session is a weaker credential than the provider key it would otherwise reveal.

configured · boolean · required

Whether Warp has everything it needs to answer a question: enabled, with a provider and a model, and an embedding space - embedding provider, embedding model, a positive embedding dimension and a namespace - since semantic search over the logs is part of answering. A key is deliberately not part of this test, since a provider using ambient credentials legitimately needs none.

enabled · boolean · required

Whether the operator has switched Warp on.

provider · string · required

The provider of Warp's default model, e.g. openai. The default answers every chat request that names no model.

Example:

"openai"

model · string · required

Warp's default model.

Example:

"gpt-4o"

max_iterations · integer · default: 8 · required

How many times Warp may call tools and feed the results back before it must answer with what it has. Resolved value, so a row that never set one reports the default rather than zero.

Required range: 1 <= x <= 20

request_timeout_seconds · integer · default: 120 · required

Bound on a single upstream call. Resolved value.

history_retention_days · integer · default: 30 · required

How long a saved chat is kept after its last turn. Resolved value, so a row that never set one reports the default rather than zero.

Deliberately separate from logs_store.retention_days: how long request telemetry is worth storing and how long someone's conversations stay theirs to reopen are different questions, and one number cannot answer both without either discarding transcripts early or keeping logs late.

Required range: x >= 1

embedding_provider · string · required

Provider used to embed gateway conversations for semantic search.

Example:

"openai"

embedding_model · string · required

Embedding model used for both indexing and queries.

Example:

"text-embedding-3-small"

embedding_dimension · integer · required

Required range: x >= 0

Example:

1536

log_vector_store_namespace · string · default: BifrostWarpLogs · required

semantic_search_threshold · number · default: 0.8 · required

Required range: x <= 1

semantic_search_limit · integer · default: 10 · required

Required range: 1 <= x <= 25

vector_store_connected · boolean · required · read-only

Whether the shared runtime vector store is connected.

api_key_id · string

Which of the provider's configured keys the default model uses. A reference, not a credential, so it round-trips in the clear - there is nothing here worth redacting. Empty when the provider needs no key.

additional_models · object[]

The other models an operator has exposed. A chat request may name any of them, or the default, by provider and model; nothing else is accepted. Omitted when only the default is configured.

Maximum array length: 20

Show child attributes

system_prompt_suffix · string

Appended to Warp's built-in system prompt. Additive only: an operator can teach Warp local naming conventions, but cannot remove the tool-use and scoping instructions the built-in prompt establishes.

embedding_api_key_id · string

Optional reference to one of the embedding provider's configured keys.