Authorization: Bearer $PLANCK_API_KEY. Use Planck-Auth when you need Authorization to carry a provider key for BYOK.
Planck-* headers are canonical. Existing Bifrost-* headers remain accepted;
when both forms are present, the Planck value takes precedence. See
Bifrost compatibility.Authentication
string
Standard bearer auth. Use
Bearer <PLANCK_API_KEY> for normal gateway requests.string
Planck-specific auth header. Use this when
Authorization must contain a
provider API key.string
Alternate API key header for Planck keys.
string
Explicit BYOK provider key header. Use this for OpenAI, Anthropic, or custom
target provider keys.
string
Alternate explicit BYOK provider key header.
Routing
string
Optional request-level billing mode:
byok, ptb, or auto. Omitted/auto
uses stored BYOK first, then PTB. Explicit byok or ptb is strict and fails
if that mode is unavailable.string
Base URL for an approved custom or self-hosted OpenAI-compatible target.
Custom targets are BYOK-only and are only available for supported operations.
string
Alternate OpenAI-compatible base URL override for OpenAI-compatible requests.
string
Controls request/response body mapping for custom target routing. Supported
values are
OPENAI, RESPONSES, and NO_MAPPING.string
Overrides the model used for cost calculation and provider mapping when the
model cannot be derived from the request.
JSON string
Defines an explicit fallback chain. Each item can include
target-url,
headers, onCodes, and bodyKeyOverride.Request Identity
string
Optional request UUID. If omitted, Planck generates one.
string
User identifier for analytics, cost attribution, sessions, and user metrics.
string
Optional Stripe customer identifier for billing-related workflows.
string
Optional node or deployment identifier for routing and analytics.
Custom Properties
string
Adds custom metadata to the request. For example,
Planck-Property-Environment: production.string
Groups requests into a session.
string
Tracks nested request paths within a session.
string
Human-readable session name.
Memory
boolean
Opts a request into user memory when org, feature flag, and context profile
settings also allow memory. If omitted or false, the request remains
pass-through for memory. Advanced personalization layers, such as personalized
ranking and persona hints, use this same explicit opt-in path.
string
Optional memory namespace within an organization and user, such as an app ID,
project, customer tenant, or
default.Planck Context
string
Selects an organization knowledge base by UUID. The authenticated API key or
user must have read access.
x-planck-knowledge-base remains a deprecated
compatibility alias; when both are present, Planck-Knowledge-Base wins.string
Selects up to 16 comma-separated managed knowledge pack UUIDs. Every pack must
be active and granted either directly to the request organization or by its
tier policy. This is additive with
Planck-Knowledge-Base and
context-profile sources.string
Selects a workflow context.
string
Selects an environment such as
development, staging, or production.string
Selects a context profile.
Caching
boolean
Enables response caching for eligible requests.
string
Sets cache duration, for example
max-age=3600.string
Sets how many different responses can be cached for the same key.
string
Adds a cache namespace, such as a user or tenant id.
string
Comma-separated JSON keys to exclude from cache key generation.
Retries
boolean
Enables automatic retry behavior.
string
Maximum retry attempts.
string
Exponential backoff factor.
string
Minimum retry delay in milliseconds.
string
Maximum retry delay in milliseconds.
Prompt And Safety
string
Associates the request with a managed prompt.
string
Selects prompt behavior, such as testing mode.
string
Selects a prompt version.
string
Selects prompt formatting behavior.
string
Human-readable prompt name.
boolean
Enables prompt security checks.
boolean
Alias for prompt security checks.
string
Advanced prompt security mode.
boolean
Enables moderation checks for supported request paths.
Streaming And Timeouts
boolean
Forces OpenAI-compatible stream formatting.
boolean
Requests usage data in streamed responses when supported.
boolean
Requests an increased timeout for long-running operations.
Privacy
boolean
Omits request body data from logs where supported.
boolean
Omits response body data from logs where supported.
Integrations
string
PostHog project key.
string
PostHog host.
string
Lytix integration key.
string
Lytix host.
boolean
Enables configured webhook side effects for the request.
Experiments
string
Experiment identifier.
string
Experiment column identifier.
string
Experiment row index.
Manual Access
string
Manual access key for approved manual logging or access workflows.
Response Headers
Legacy
Bifrost-* response names are emitted alongside these headers during
the compatibility period.
Webhook Delivery Headers
Legacy
Bifrost-* webhook names are emitted alongside these headers during
the compatibility period.