## 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. |