Ask Warp a question

Runs Warp’s agent loop over the deployment’s telemetry and returns an answer.

The route is always registered, and answers 503 while Warp cannot work. The body carries a machine-readable reason, so “present but unusable” stays distinguishable from “absent” without the state being permanent: a deployment that enables logging after startup begins serving this route without a restart.

The model’s context is client-sent: messages carries the thread so far. Where Warp history is available the server also files each turn under conversation_id so the thread can be listed and reopened through /api/warp/conversations. Omit conversation_id to start a new thread; its id comes back on the done event or in the JSON body.

Data visibility equals the caller’s own. Every tool query runs against the caller’s row-level scope, so Warp can never surface data the caller could not already retrieve from the logs API directly.

The turn runs on Warp’s default model unless the body names another with provider and model. Only a model the configuration exposes is accepted; anything else is a 400 and no model is called.

With stream: true (the default) the response is text/event-stream. Both modes run the identical loop; only the sink differs.

Enterprise RBAC: requires WarpSession View.

POST /api/warp/chat

Error

A valid request URL is required to generate request examples

200

<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

messages · object[] · required

The full conversation so far, oldest first. Roles must be user or assistant; a client-supplied system turn is rejected, since it would let a caller displace the instructions that keep Warp from inventing numbers.

Long threads are trimmed server-side, always keeping the opening turn - it usually carries the framing everything after it depends on.

Minimum array length: 1

Show child attributes

conversation_id · string

Continues an existing thread in the caller's history. Omit it to start a new one; the new thread's id comes back on the done event or in the JSON body.

Maximum string length: 36

provider · string

With model, names which of Warp's configured models answers this turn: the default, or one of additional_models. Omit both to use the default. A pair the operator has not exposed is rejected with 400, so a request can only ever choose among the configured models, and the provider key is always the configured entry's own.

Example:

"anthropic"

model · string

See provider. The two are given together or not at all.

Example:

"claude-sonnet-5"

stream · boolean · default: true

Selects the transport, not the behaviour. true streams SSE frames; false returns one JSON body. Both run the same loop.

Response

200

text/event-stream

The answer. text/event-stream when streaming, otherwise a single JSON body.

SSE frames are event: <type> with a JSON payload. Types are start, delta (an answer fragment), tool_call_start, tool_call_end, error and done.

error is terminal and is never followed by done. A client that treats done as the only completion signal will read a failed request as a successful one, so both must end the stream.

The response is of type string.