Routing & passthrough

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

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.

from openai import OpenAI
client = OpenAI(
    base_url="https://api.respan.ai/api/",
    api_key="YOUR_RESPAN_API_KEY",
)
# Switch provider by changing the slug, not the SDK or base URL.
client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": "Hi"}])
client.chat.completions.create(model="claude-sonnet-4-5-20250929", messages=[{"role": "user", "content": "Hi"}])
client.chat.completions.create(model="gemini-2.5-flash", messages=[{"role": "user", "content": "Hi"}])

Endpoints:

See Create chat completion and Create response for the full schema.

Route Responses to Perplexity Agent API

Set the route header on POST /api/responses:

X-Respan-Route-Provider: perplexity

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:

{
  "preset": "medium",
  "input": "Research the latest developments in small language models.",
  "max_steps": 4
}

See Responses API 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:

curl https://api.respan.ai/api/openai/v1/chat/completions \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hi"}]}'

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

from openai import OpenAI
client = OpenAI(
    api_key="YOUR_RESPAN_API_KEY",
    base_url="https://api.respan.ai/api/openai/v1",
)
client.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hi"}])

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

curl https://api.respan.ai/api/xai/v1/chat/completions \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4", "messages": [{"role": "user", "content": "Hi"}]}'

Groq, Mistral, Together AI, DeepSeek, Perplexity, and more work the same way. See Chat completions passthrough for the full provider list, guaranteed behaviors, and headers.

Anthropic

import anthropic
client = anthropic.Anthropic(
    base_url="https://api.respan.ai/api/anthropic/",
    api_key="YOUR_RESPAN_API_KEY",
)
message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)

For the Anthropic CLI or Claude Code:

export ANTHROPIC_BASE_URL="https://api.respan.ai/api/anthropic/"
export ANTHROPIC_AUTH_TOKEN="YOUR_RESPAN_API_KEY"

Google Gemini

from google import genai
client = genai.Client(
    api_key="YOUR_RESPAN_API_KEY",
    http_options={"base_url": "https://api.respan.ai/api/google/gemini"},
)

For the Gemini CLI:

export GEMINI_API_KEY="YOUR_RESPAN_API_KEY"
export GOOGLE_GEMINI_BASE_URL="https://api.respan.ai/api/google/gemini"

Google Vertex AI

export GOOGLE_GEMINI_BASE_URL="https://api.respan.ai/api/google/vertexai/"

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.

from openai import OpenAI
client = OpenAI(
    base_url="https://api.respan.ai/api/openrouter/v1",
    api_key="YOUR_RESPAN_API_KEY",
    default_headers={"x-openrouter-api-key": "YOUR_OPENROUTER_API_KEY"},
)
response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4-5",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={
        "provider": {"order": ["anthropic"]},
        "reasoning": {"effort": "high"},
    },
)

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:

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) 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 for details.