Responses API | Respan Docs

Choose a route

Route	Header	Model shape	Request-scoped provider credentials
OpenAI	None, or `X-Respan-Route-Provider: openai`	A supported OpenAI model, such as `gpt-4o-mini`	Exact model key with `api_key`
Azure OpenAI	`X-Respan-Route-Provider: azure`	`azure/<deployment>` is recommended	Exact model key with `api_key`, `api_base`, and `api_version`
Perplexity Agent API	`X-Respan-Route-Provider: perplexity`	Provider-prefixed `model`, `preset`, or `models`	Empty-string provider selector with `api_key`

The Perplexity route is header-only. Putting route_provider_override: perplexity in the body, respan_params, or a stored prompt does not activate it. The header value is case-insensitive and surrounding whitespace is ignored.

The Perplexity value applies only to POST /api/responses. It is ignored on Chat Completions and provider passthrough endpoints. Without the header, existing OpenAI routing is unchanged.

OpenAI route

OpenAI is the default route. You may omit X-Respan-Route-Provider, or set it explicitly to openai.

The BYOK request below uses two keys:

RESPAN_API_KEY authenticates the request to Respan.
OPENAI_API_KEY authenticates Respan to OpenAI for this request.

Azure OpenAI route

Set X-Respan-Route-Provider: azure to route the request through Azure OpenAI. Use an azure/-prefixed deployment name in both model and credential_override so the credential lookup is unambiguous.

Perplexity Agent API route

The default BYOK request uses two keys:

RESPAN_API_KEY authenticates the request to Respan.
PERPLEXITY_API_KEY is passed as a request-scoped provider credential.

Perplexity request shapes

Explicit model

Perplexity Agent API accepts provider-prefixed model names. Respan passes the name through unchanged.

Preset-only

Omit model and let Perplexity select one using a preset.

Logging and billing

Every successful route returns X-Respan-Log-Id.

Route	Logged provider/model behavior
OpenAI	Logs the canonical OpenAI model and standard gateway usage/cost.
Azure OpenAI	Logs the resolved `azure/<deployment>` model and Azure usage/cost.
Perplexity	Logs `provider_id: perplexity`, the actual model returned by Perplexity, and provider-reported cost when present.

Troubleshooting

Symptom	Fix
OpenAI or Azure request fails before reaching the provider	Include both required `input` and `model` fields.
`401` asks for an OpenAI key	Add an OpenAI provider integration or supply an exact-model `credential_override`.
Azure reports missing credential fields	Supply `api_key`, `api_base`, and `api_version`, or update the stored Azure integration.
Azure cannot find the deployment	Confirm the value after `azure/` matches the deployment name and that `api_base` points to the correct Azure resource.
Request follows the OpenAI route	Add `X-Respan-Route-Provider: perplexity`; a body field alone is ignored.
`401` asks for a Perplexity key even though you entered one	In a request-scoped override, keep the selector as the empty string: `credential_override[""]`. In the API Explorer, reselect the Perplexity example to clear fields left by another provider.
Perplexity-only fields disappear	Confirm the header is present on `POST /api/responses`, not Chat Completions.