---
title: "Request Options"
description: "Complete reference of all request options supported by Bifrost, including HTTP headers for the gateway and context keys for the Go SDK."
icon: "list"
---
Bifrost provides request options that control behavior, enable features, and pass metadata. In the gateway, these are set via HTTP headers (prefixed with `x-bf-`). In the Go SDK, they are set via context keys. This document covers both approaches.
## Complete Reference
| Context Key | Header | Type | Description |
|-------------|--------|------|-------------|
| `BifrostContextKeyVirtualKey` | `x-bf-vk` | `string` | Virtual key identifier for governance |
| `BifrostContextKeyAPIKeyName` | `x-bf-api-key` | `string` | Explicit API key name selection |
| `BifrostContextKeyAPIKeyID` | `x-bf-api-key-id` | `string` | Explicit API key ID selection (takes priority over name) |
| `BifrostContextKeySessionID` | `x-bf-session-id` | `string` | Session ID for key stickiness (requires KV store) |
| `BifrostContextKeySessionTTL` | `x-bf-session-ttl` | `time.Duration` | Session-to-key cache TTL (duration string or seconds) |
| `BifrostContextKeyRequestID` | `x-request-id` | `string` | Custom request ID for tracking |
| `BifrostContextKeySendBackRawRequest` | `x-bf-send-back-raw-request` | `bool` | Include raw provider request in the response |
| `BifrostContextKeySendBackRawResponse` | `x-bf-send-back-raw-response` | `bool` | Include raw provider response in the response |
| `BifrostContextKeyStoreRawRequestResponse` | `x-bf-store-raw-request-response` | `bool` | Persist raw request/response in log records |
| `BifrostContextKeyPassthroughExtraParams` | `x-bf-passthrough-extra-params` | `bool` | Enable passthrough for extra parameters |
| `BifrostContextKeyExtraHeaders` | `x-bf-eh-*` | `map[string][]string` | Custom headers forwarded to provider |
| `BifrostContextKeyDirectKey` | `-` | `schemas.Key` | Direct key credentials (Go SDK only) |
| `BifrostContextKeySkipKeySelection` | `-` | `bool` | Skip key selection process (Go SDK only) |
| `BifrostContextKeyURLPath` | `-` | `string` | Custom URL path appended to provider base URL (Go SDK only) |
| `BifrostContextKeyUseRawRequestBody` | `-` | `bool` | Use raw request body (Go SDK only, requires RawRequestBody field) |
| `semanticcache.CacheKey` | `x-bf-cache-key` | `string` | Custom cache key |
| `semanticcache.CacheTTLKey` | `x-bf-cache-ttl` | `time.Duration` | Cache TTL (duration string or seconds) |
| `semanticcache.CacheThresholdKey` | `x-bf-cache-threshold` | `float64` | Similarity threshold (0.0-1.0) |
| `semanticcache.CacheTypeKey` | `x-bf-cache-type` | `string` | Cache type |
| `semanticcache.CacheNoStoreKey` | `x-bf-cache-no-store` | `bool` | Prevent caching |
| `mcp-include-clients` | `x-bf-mcp-include-clients` | `[]string` | Filter MCP clients (comma-separated). |
| `mcp-include-tools` | `x-bf-mcp-include-tools` | `[]string` | Filter MCP tools (`clientName-toolName` format, comma-separated) |
| `BifrostContextKeyMCPExtraHeaders` | *(any header in a client's `allowed_extra_headers`)* | `map[string][]string` | Headers forwarded to MCP servers at tool execution time, filtered per-client against `allowed_extra_headers` |
| `maxim.TraceIDKey` | `x-bf-maxim-trace-id` | `string` | Maxim trace ID |
| `maxim.GenerationIDKey` | `x-bf-maxim-generation-id` | `string` | Maxim generation ID |
| `maxim.TagsKey` | `x-bf-maxim-*` | `map[string]string` | Maxim tags (custom tag names) |
| `BifrostContextKey(labelName)` | `x-bf-prom-*` | `string` | Prometheus metric labels |
## Request Configuration Options
These options configure how Bifrost processes and forwards requests.
### Virtual Key
**Context Key:** `BifrostContextKeyVirtualKey`
**Header:** `x-bf-vk`
**Type:** `string`
**Required:** Yes (when governance **is** enabled and enforced)
Specify the virtual key identifier for governance, routing, and access control.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-vk: sk-bf-*' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeyVirtualKey, "sk-bf-*")
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
Virtual keys can also be passed via `Authorization: Bearer vk-*`, `x-api-key: vk-*`, or `x-goog-api-key: vk-*` headers when the value starts with the virtual key prefix.
### API Key Selection
Bifrost supports selecting a specific key by **ID** or **name**. When both are present, ID takes priority.
#### By ID
**Context Key:** `BifrostContextKeyAPIKeyID`
**Header:** `x-bf-api-key-id`
**Type:** `string`
**Required:** No
Explicitly select a key by its unique ID. Takes priority over name selection when both are provided.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-api-key-id: key-uuid-1234' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeyAPIKeyID, "key-uuid-1234")
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
#### By Name
**Context Key:** `BifrostContextKeyAPIKeyName`
**Header:** `x-bf-api-key`
**Type:** `string`
**Required:** No
Explicitly select a named API key from your configured keys.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-api-key: premium-key' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeyAPIKeyName, "premium-key")
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
### Session Stickiness (Session ID)
**Context Key:** `BifrostContextKeySessionID`
**Header:** `x-bf-session-id`
**Type:** `string`
**Required:** No
Bind a session to a specific API key so that requests with the same session ID consistently use the same key. Useful for predictable rate-limit buckets, cost attribution per user, and consistent model routing per session.
On the first request for a session ID, Bifrost selects a key and caches the binding in the KV store. Subsequent requests with the same session ID reuse the cached key as long as it remains valid.
**Retry and Fallback Behavior:**
- **Retries**: Session stickiness persists across retry attempts. If a request fails and is retried, the same sticky key is used.
- **Fallbacks**: When falling back to a different provider (e.g., from OpenAI to Anthropic), session stickiness is disabled and a new key is selected for the fallback provider. This ensures availability when the primary provider's keys are exhausted or failing.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-session-id: user-123-session-abc' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeySessionID, "user-123-session-abc")
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
### Session TTL
**Context Key:** `BifrostContextKeySessionTTL`
**Header:** `x-bf-session-ttl`
**Type:** `time.Duration` (header value: duration string like `"30m"` or `"1h"`, or seconds as integer)
**Required:** No
Optional. Controls how long the session-to-key binding is cached. If not set, Bifrost uses 1 hour. The TTL is refreshed on each request so active sessions do not expire.
Accepts duration strings (`"30s"`, `"5m"`, `"1h"`) or plain numbers (treated as seconds).
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-session-id: user-123-session-abc' \
--header 'x-bf-session-ttl: 30m' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeySessionID, "user-123-session-abc")
ctx = context.WithValue(ctx, schemas.BifrostContextKeySessionTTL, 30*time.Minute)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
### Request ID
**Context Key:** `BifrostContextKeyRequestID`
**Header:** `x-request-id`
**Type:** `string`
**Required:** No
Set a custom request ID for tracking and correlation. If not provided, Bifrost generates a UUID.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-request-id: req-12345-abc' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeyRequestID, "req-12345-abc")
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
### Send Back Raw Request
**Context Key:** `BifrostContextKeySendBackRawRequest`
**Header:** `x-bf-send-back-raw-request`
**Type:** `bool` (header values: `"true"` or `"false"`)
**Required:** No
Include the exact JSON body sent to the provider alongside Bifrost's standardized response. Accepts `"true"` or `"false"` — either value fully overrides the provider-level `send_back_raw_request` config for this request.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-send-back-raw-request: true' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeySendBackRawRequest, true)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
// Access raw request
if response.ChatResponse != nil {
rawReq := response.ChatResponse.ExtraFields.RawRequest
}
```
The raw request appears in `extra_fields.raw_request`:
```json
{
"choices": [...],
"usage": {...},
"extra_fields": {
"provider": "openai",
"raw_request": {
// Exact JSON sent to the provider
}
}
}
```
### Send Back Raw Response
**Context Key:** `BifrostContextKeySendBackRawResponse`
**Header:** `x-bf-send-back-raw-response`
**Type:** `bool` (header values: `"true"` or `"false"`)
**Required:** No
Include the original provider response alongside Bifrost's standardized response format. Accepts `"true"` or `"false"` — either value fully overrides the provider-level `send_back_raw_response` config for this request.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-send-back-raw-response: true' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeySendBackRawResponse, true)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
// Access raw response
if response.ChatResponse != nil {
rawResp := response.ChatResponse.ExtraFields.RawResponse
}
```
The raw response appears in `extra_fields.raw_response`:
```json
{
"choices": [...],
"usage": {...},
"extra_fields": {
"provider": "openai",
"raw_response": {
// Original provider response here
}
}
}
```
### Store Raw Request/Response
**Context Key:** `BifrostContextKeyStoreRawRequestResponse`
**Header:** `x-bf-store-raw-request-response`
**Type:** `bool` (header values: `"true"` or `"false"`)
**Required:** No
Persist the raw provider request and response in the log record. Accepts `"true"` or `"false"` — either value fully overrides the provider-level `store_raw_request_response` config for this request.
This is orthogonal to the send-back flags: enabling this does not affect whether raw data appears in the API response, and enabling send-back does not automatically store raw data in logs. Use this when you want observability into provider payloads without necessarily exposing them to the caller, or combine it with `x-bf-send-back-raw-*` to do both.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-store-raw-request-response: true' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeyStoreRawRequestResponse, true)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
// Raw data is persisted in the log record.
// ExtraFields.RawRequest/RawResponse are nil unless send-back flags are also enabled.
```
`x-bf-store-raw-request-response` only has effect when the logging plugin is active — raw data is written to the log record by the logging plugin. Without it, enabling this flag captures the data but nothing persists it.
`x-bf-store-raw-request-response` and `x-bf-send-back-raw-*` are orthogonal — you can enable any combination. Enabling store does not send data back to the caller; enabling send-back does not persist data in logs. Enable both to do both.
### Passthrough Extra Parameters
**Context Key:** `BifrostContextKeyPassthroughExtraParams`
**Header:** `x-bf-passthrough-extra-params`
**Type:** `bool` (header value: `"true"`)
**Required:** No
Enable passthrough mode for extra parameters. When enabled, any parameters in `extra_params` (or provider-specific extra parameter fields) will be merged directly into the request sent to the provider.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-passthrough-extra-params: true' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}],
"custom_param": "value",
"nested_param": {
"a": "value",
"b": 123
}
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeyPassthroughExtraParams, true)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
Params: &schemas.ChatParameters{
ExtraParams: map[string]interface{}{
"custom_param": "value",
"nested_param": map[string]interface{}{
"a": "value",
"b": 123,
},
},
},
})
```
- Only works for JSON requests, not multipart/form-data requests
- Parameters already handled by Bifrost are not duplicated
- Nested parameters are merged recursively with existing structures
### Direct Key (Go SDK Only)
**Context Key:** `BifrostContextKeyDirectKey`
**Header:** `-` (not available via HTTP)
**Type:** `schemas.Key`
**Required:** No
Bypass key selection and provide credentials directly. Useful for dynamic key scenarios.
```go
directKey := schemas.Key{
Value: "sk-direct-api-key",
Models: []string{"gpt-4o"},
Weight: 1.0,
}
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeyDirectKey, directKey)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o",
Input: messages,
})
```
### Skip Key Selection (Go SDK Only)
**Context Key:** `BifrostContextKeySkipKeySelection`
**Header:** `-` (not available via HTTP)
**Type:** `bool`
**Required:** No
Skip the key selection process entirely and pass an empty key to the provider. Useful for providers that don't require authentication or when using ambient credentials.
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeySkipKeySelection, true)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
### Custom URL Path (Go SDK Only)
**Context Key:** `BifrostContextKeyURLPath`
**Header:** `-` (not available via HTTP)
**Type:** `string`
**Required:** No
Append a custom path to the provider's base URL. Useful for accessing provider-specific endpoints.
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeyURLPath, "/custom/endpoint")
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
### Raw Request Body (Go SDK Only)
**Context Key:** `BifrostContextKeyUseRawRequestBody`
**Header:** `-` (not available via HTTP)
**Type:** `bool`
**Required:** No
Send a raw request body instead of Bifrost's standardized format. The provider receives your payload as-is. You must both enable the context key AND set the `RawRequestBody` field on your request.
```go
// Prepare your raw JSON payload
rawPayload := []byte(`{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello!"}],
"custom_field": "provider-specific-value"
}`)
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeyUseRawRequestBody, true)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o",
RawRequestBody: rawPayload,
})
```
When using raw request body, Bifrost bypasses its request conversion and sends your payload directly to the provider. You're responsible for ensuring the payload matches the provider's expected format.
## Custom Headers
### Extra Headers (x-bf-eh-*)
**Context Key:** `BifrostContextKeyExtraHeaders`
**Header Pattern:** `x-bf-eh-{header-name}`
**Type:** `map[string][]string`
**Required:** No
Pass custom headers to providers. The `x-bf-eh-` prefix is stripped before forwarding.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-eh-user-id: user-123' \
--header 'x-bf-eh-tracking-id: trace-456' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
extraHeaders := map[string][]string{
"user-id": {"user-123"},
"tracking-id": {"trace-456"},
}
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKeyExtraHeaders, extraHeaders)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
The headers `x-bf-eh-user-id` and `x-bf-eh-tracking-id` are forwarded to the provider as `user-id` and `tracking-id` respectively.
**Example use cases:**
- User identification: `x-bf-eh-user-id`, `x-bf-eh-tenant-id`
- Request tracking: `x-bf-eh-correlation-id`, `x-bf-eh-trace-id`
- Custom metadata: `x-bf-eh-department`, `x-bf-eh-cost-center`
- A/B testing: `x-bf-eh-experiment-id`, `x-bf-eh-variant`
## Semantic Cache Options
These options control semantic caching behavior.
### Cache Key
**Context Key:** `semanticcache.CacheKey`
**Header:** `x-bf-cache-key`
**Type:** `string`
**Required:** No
Specify a custom cache key for semantic cache lookups.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-cache-key: custom-key-123' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, semanticcache.CacheKey, "custom-key-123")
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
### Cache TTL
**Context Key:** `semanticcache.CacheTTLKey`
**Header:** `x-bf-cache-ttl`
**Type:** `time.Duration` (header value: duration string like `"30s"` or `"5m"`, or seconds as integer)
**Required:** No
Set a custom time-to-live for cached responses.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-cache-ttl: 300' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, semanticcache.CacheTTLKey, 5*time.Minute)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
Accepts duration strings (`"30s"`, `"5m"`, `"1h"`) or plain numbers (treated as seconds).
### Cache Threshold
**Context Key:** `semanticcache.CacheThresholdKey`
**Header:** `x-bf-cache-threshold`
**Type:** `float64` (range: 0.0 to 1.0)
**Required:** No
Set the similarity threshold for semantic cache matching.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-cache-threshold: 0.85' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, semanticcache.CacheThresholdKey, 0.85)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
### Cache Type
**Context Key:** `semanticcache.CacheTypeKey`
**Header:** `x-bf-cache-type`
**Type:** `semanticcache.CacheType` (string)
**Required:** No
Specify the cache type for this request.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-cache-type: semantic' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, semanticcache.CacheTypeKey, semanticcache.CacheTypeSemantic)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
### Cache No Store
**Context Key:** `semanticcache.CacheNoStoreKey`
**Header:** `x-bf-cache-no-store`
**Type:** `bool` (header value: `"true"`)
**Required:** No
Prevent caching of this request/response.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-cache-no-store: true' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, semanticcache.CacheNoStoreKey, true)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
## MCP (Model Context Protocol) Options
These options control MCP client and tool filtering.
### Include Clients
**Context Key:** `mcp-include-clients`
**Header:** `x-bf-mcp-include-clients`
**Type:** `[]string` (comma-separated values)
**Required:** No
Filter MCP clients to include only the specified ones.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-mcp-include-clients: client1,client2' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKey("mcp-include-clients"), []string{"client1", "client2"})
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
### Include Tools
**Context Key:** `mcp-include-tools`
**Header:** `x-bf-mcp-include-tools`
**Type:** `[]string` (comma-separated values)
**Required:** No
Filter MCP tools to include only the specified ones. Values must use the `clientName-toolName` format (e.g. `gmail-send_email`). Use `clientName-*` to include all tools from a client.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-mcp-include-tools: gmail-send_email,filesystem-read_file' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKey("mcp-include-tools"), []string{"gmail-send_email", "filesystem-read_file"})
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
## Maxim Observability Options
These options enable Maxim observability integration and tag propagation.
### Maxim Trace ID
**Context Key:** `maxim.TraceIDKey`
**Header:** `x-bf-maxim-trace-id`
**Type:** `string`
**Required:** No
Set the Maxim trace ID for distributed tracing.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-maxim-trace-id: trace-12345' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, maxim.TraceIDKey, "trace-12345")
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
### Maxim Generation ID
**Context Key:** `maxim.GenerationIDKey`
**Header:** `x-bf-maxim-generation-id`
**Type:** `string`
**Required:** No
Set the Maxim generation ID for request correlation.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-maxim-generation-id: gen-12345' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, maxim.GenerationIDKey, "gen-12345")
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
### Maxim Tags (x-bf-maxim-*)
**Context Key:** `maxim.TagsKey`
**Header Pattern:** `x-bf-maxim-{tag-name}`
**Type:** `map[string]string`
**Required:** No
Add custom tags to Maxim traces. Any header starting with `x-bf-maxim-` that isn't a reserved header becomes a tag.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-maxim-environment: production' \
--header 'x-bf-maxim-team: engineering' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
tags := map[string]string{
"environment": "production",
"team": "engineering",
}
ctx := context.Background()
ctx = context.WithValue(ctx, maxim.TagsKey, tags)
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
## Prometheus Options
**Context Key:** `BifrostContextKey(labelName)`
**Header Pattern:** `x-bf-prom-{label-name}`
**Type:** `string`
**Required:** No
Add custom labels to Prometheus metrics. The `x-bf-prom-` prefix is stripped and the remainder becomes the label name.
```bash
curl --location 'http://localhost:8080/v1/chat/completions' \
--header 'x-bf-prom-environment: production' \
--header 'x-bf-prom-team: engineering' \
--header 'Content-Type: application/json' \
--data '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```go
ctx := context.Background()
ctx = context.WithValue(ctx, schemas.BifrostContextKey("environment"), "production")
ctx = context.WithValue(ctx, schemas.BifrostContextKey("team"), "engineering")
response, err := client.ChatCompletionRequest(schemas.NewBifrostContext(ctx, schemas.NoDeadline), &schemas.BifrostChatRequest{
Provider: schemas.OpenAI,
Model: "gpt-4o-mini",
Input: messages,
})
```
## Security Denylist
Bifrost maintains a security denylist of headers that are **never** forwarded to providers, regardless of configuration:
- `proxy-authorization`
- `cookie`
- `host`
- `content-length`
- `connection`
- `transfer-encoding`
- `x-api-key` (when used via `x-bf-eh-*`)
- `x-goog-api-key` (when used via `x-bf-eh-*`)
- `x-bf-api-key` (when used via `x-bf-eh-*`)
- `x-bf-vk` (when used via `x-bf-eh-*`)
## Internal Context Keys
These context keys are read-only and set when request is completed. **Do not set these values.**
The following context keys are set by Bifrost internally.
- `BifrostContextKeySelectedKeyID` - The selected provider key ID.
- `BifrostContextKeySelectedKeyName` - The selected provider key name.
- `BifrostContextKeyNumberOfRetries` - Number of retry attempts made.
- `BifrostContextKeyFallbackIndex` - Index of fallback provider used.
- `BifrostContextKeyFallbackRequestID` - Request ID for fallback attempts.
- `BifrostContextKeyStreamEndIndicator` - Indicates if stream completed.
- `BifrostContextKeyIntegrationType` - Format type of integration used.
- `BifrostContextKeyUserAgent` - User agent from request.
## Related Documentation
- **[Gateway Provider Configuration](../quickstart/gateway/provider-configuration)** - Configure providers and headers
- **[Go SDK Context Keys](../quickstart/go-sdk/context-keys)** - Programmatic context key usage
- **[Virtual Keys](../features/governance/virtual-keys)** - Virtual key usage and governance
- **[Semantic Cache](../features/semantic-caching)** - Caching configuration