# Respan API Endpoints

Respan exposes two different endpoint shapes. Pick whichever fits the SDK or tool you already use.

| Shape | Base URL | When to use |
| --- | --- | --- |
| **Unified router** | `https://api.respan.ai/api/` | Point any OpenAI-compatible SDK here. Switch providers by changing the `model` slug. |
| **Provider passthrough** | `https://api.respan.ai/api/openai/v1`, `.../xai/v1`, `.../anthropic/`, `.../google/gemini`, `.../google/vertexai/`, `.../openrouter/v1` | Drop-in replacement for the provider’s own SDK or CLI. Keep using the provider’s native API shape and SDK. |

Every request through either shape is automatically logged.

## Unified router

The unified router accepts the OpenAI Chat Completions and Responses API formats. You point any OpenAI-compatible SDK at `https://api.respan.ai/api/` and call models from any provider by changing the `model` slug.

### Endpoints:

| Endpoint | Format |
| --- | --- |
| `POST /api/chat/completions` | OpenAI Chat Completions |
| `POST /api/responses` | OpenAI Responses API, including Perplexity Agent API routing |
| `POST /api/embeddings` | OpenAI Embeddings |

See [Create chat completion](/content/docs/apis/gateway/create-chat-completion/index.html) and [Create response](/content/docs/apis/gateway/create-response/index.html) for the full schema.

### Route Responses to Perplexity Agent API

Set the route header on `POST /api/responses`:

This header-only opt-in accepts explicit provider-prefixed models, preset-only requests, fallback model chains, streaming, tools, and other Perplexity Agent API parameters. For example:

See [Responses API](/content/docs/documentation/features/gateway/responses-api/index.html) for setup, request shapes, credentials, and billing behavior.

## Provider passthrough

Passthrough endpoints accept the provider’s native request and response format unchanged. Use them when you want to keep using the provider’s official SDK or CLI without switching to OpenAI-compatible code.

### Chat completions (OpenAI, xAI, and other OpenAI-shaped providers)

For providers with an OpenAI-shaped API, `POST /api/{provider}/v1/chat/completions` relays your exact chat-completions payload and returns the provider’s exact response, untranslated. `Authorization` carries your Respan key, not the provider’s.

**OpenAI:**

With the OpenAI SDK, repoint `base_url` and pass your Respan key. Nothing else changes:

**xAI (Grok)** is the same call with a different path segment:

Groq, Mistral, Together AI, DeepSeek, Perplexity, and more work the same way. See [Chat completions passthrough](/content/docs/documentation/features/gateway/chat-completions-passthrough/index.html) for the full provider list, guaranteed behaviors, and headers.

### Anthropic

### Google Gemini

### Google Vertex AI

### OpenRouter

The OpenRouter passthrough relays your request to OpenRouter with no Respan schema in between, and returns OpenRouter’s own bytes, status and headers. Point any OpenAI-compatible SDK at it.

This endpoint is BYOK. `Authorization` carries your Respan API key and `x-openrouter-api-key` carries your OpenRouter API key. Both are required, and there is no fallback to Respan gateway credits. On the unified router you supply an OpenRouter key through `customer_credentials` or your provider settings instead.

Use OpenRouter’s own model slug. An `openrouter/` prefix is also accepted and is stripped before the call goes upstream.

The unified router already forwards object-shaped `reasoning` and `provider` for `openrouter/*` models, so reach for the passthrough when you need more than those two:

|  | Unified router | OpenRouter passthrough |
| --- | --- | --- |
| Object-shaped `reasoning` and `provider` | Forwarded | Forwarded |
| Any other OpenRouter body field, such as `reasoning_effort: "none"` | Not forwarded | Forwarded |
| A field OpenRouter adds in future | Not forwarded until Respan models it | Forwarded, no change needed |
| Response fields `provider`, `native_finish_reason`, `reasoning_details` | Not returned | Returned |
| An invalid field | Rejected against the Respan schema | Rejected by OpenRouter, with its own error body |
| Upstream `402`, `404`, `429` | Normalized into a gateway error | Returned as that same status |

The `http-referer` and `x-title` headers, plus any `x-openrouter-*` header you send, are forwarded upstream. Streaming works the same way: set `"stream": true` and the server-sent event stream is relayed frame by frame. Either shape is logged in Respan.

See [OpenRouter (gateway)](/content/docs/gateway/openrouter/index.html) for the unified router setup and `openrouter/`-prefixed model slugs.

## Which one should I use?

- **Use the unified router** if you want one SDK and one base URL across providers, want to use Respan features like inline routing or fallbacks, or are starting fresh.
- **Use a passthrough** if you already have provider-native code, want a provider’s CLI (Claude Code, Gemini CLI) to flow through Respan unchanged, or need a feature only the provider’s native API exposes.

Both can be mixed in the same project. For example, route your app’s OpenAI SDK calls through the unified router and route Claude Code through the Anthropic passthrough.

## Pin a provider for a passthrough call

By default a passthrough request resolves to its native provider (Anthropic passthrough goes to Anthropic, etc.). To keep a passthrough’s request shape but route the call to a different provider (e.g. send Anthropic-format requests to Vertex AI or Bedrock), use the `X-Respan-Route-Provider` header. See [Providers & models](/content/docs/documentation/features/gateway/custom-models#pin-a-provider/index.html) for details.