Skip to content
ProxAI

Routing and Providers

Routing and Providers

Section titled “Routing and Providers”

Routing answers one question: which configured provider should handle this inbound request? Provider configuration answers another: which wire protocol and upstream endpoint does that provider use?

Request protocol vs provider protocol

Section titled “Request protocol vs provider protocol”
  • request_protocol is an optional route filter based on the inbound endpoint ProxAI detected.
  • Provider protocol controls the outbound wire format sent upstream.
  • If a route omits request_protocol, it can match the actual inbound protocol detected from the request path.
  • If a route sets request_protocol and the model matches but the inbound protocol differs, ProxAI returns a configuration error instead of silently falling through.

Supported protocol values

Section titled “Supported protocol values”
Protocol valueUsed byMeaning
openai_responsesRequests and providersOpenAI Responses API
openai_chat_completionsRequests and providersOpenAI Chat Completions API
anthropic_messagesRequests and providersAnthropic Messages API

Route matching model

Section titled “Route matching model”

A route usually contains:

[[routing.routes]]
name = "minimax_m3_chat"
request_protocol = "openai_chat_completions"
match_kind = "exact"
model_pattern = "MiniMax-M3-preview"
provider = "minimax"
upstream_model = "MiniMax-M3"

Important fields:

FieldRole
nameStable identifier for CLI overrides
request_protocolOptional endpoint/protocol guard
match_kindexact, glob, regex, or auto
model_patternLogical model selector
providerProvider name selected when this route matches
upstream_modelOptional model rewrite before sending upstream

Provider definition

Section titled “Provider definition”

A provider describes a concrete upstream:

[providers.minimax]
protocol = "anthropic_messages"
base_url = "https://example.invalid"
api_key = "..."
compatibility = "anthropic_compatible"
read_idle_timeout_secs = 60

Provider protocol controls whether request translation is needed. For example, an inbound openai_chat_completions request routed to an anthropic_messages provider requires the openai_chat_completions -> anthropic_messages conversion pair. Provider api_key is always sent upstream (Authorization: Bearer for OpenAI providers, x-api-key for Anthropic providers) and overrides any client-supplied auth header — see Behavior Contract C11 and C12.

Section titled “Related docs”