Skip to content

LLM header routing

Use llm-header-router when the application, or an earlier policy in the chain, must name the provider explicitly rather than leave the choice to the gateway. The router reads a request header, matches its value against an ordered mapping, and publishes the selected provider name.

Unlike the round robin policies, the header router selects a single provider rather than distributing across a pool, so it carries no suspension or failover behavior.

Parameters

Parameter Required Default Description
mappings Yes None Ordered list of header values and effective provider names. At least one mapping is required.
headerName No x-provider Header used for provider selection. Header-name lookup is case-insensitive.
defaultProvider No Unset Provider selected when the header is missing, empty, or unmatched. If unset, the primary provider is used.

The router has the following selection behavior:

  • Uses only the first value when the header appears more than once
  • Trims leading and trailing whitespace from the value
  • Matches configured values case-insensitively
  • Rejects duplicate mapping values case-insensitively
  • Preserves a non-empty provider selection made by an earlier policy
  • Leaves the routing header on the upstream request

The header router publishes provider-selection metadata but does not by itself override the named upstream. An additional provider therefore needs a matching inline transformer, or another policy that explicitly sets its upstream.

Policy reference

This policy is documented in the Policy Hub, the versioned reference for every API Platform policy. See LLM Header Router for its complete configuration.