Respan API (gateway)

The Respan API is the gateway itself. Every request is automatically traced — no SDK or instrumentation needed.

Paste this into your coding agent:


Help me set up the Respan gateway with the Respan API integration.
Follow https://www.respan.ai/docs/integrations/gateway/respan-api.md

Endpoints

API surface	Base URL	Request path	Auth
OpenAI-compatible Chat Completions	`https://api.respan.ai/api`	`/chat/completions`	`Authorization: Bearer $RESPAN_API_KEY`
Anthropic Messages	`https://api.respan.ai/api/anthropic`	`/v1/messages`	`Authorization: Bearer $RESPAN_API_KEY` or SDK `api_key`
Google Gemini SDK proxy	`https://api.respan.ai/api/google/gemini`	`/v1beta/models/{model}:generateContent`	`x-goog-api-key: $RESPAN_API_KEY`
OpenRouter passthrough	`https://api.respan.ai/api/openrouter/v1`	`/chat/completions`	`Authorization: Bearer $RESPAN_API_KEY` plus `x-openrouter-api-key`

POST /api/responses accepts the same Bearer key and serves OpenAI models (Claude and Gemini on that route return 400). Use /chat/completions for every other provider.

Environment switching: Respan doesn’t support an env parameter in API calls. To switch between environments (test/production), use different API keys — one for your test environment and another for production. Manage keys in API Keys settings .

Setup

Install packages

Install requests if you want to run the Python example below.

Terminal


pip install requests

Set environment variables

Terminal


export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

Make a request

Python


import os
import requests

response = requests.post(
    "https://api.respan.ai/api/chat/completions",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['RESPAN_API_KEY']}",
    },
    json={
        "model": "gpt-5.5",
        "messages": [{"role": "user", "content": "Say 'Hello World'"}],
    },
)
print(response.json())

TypeScript


const response = await fetch("https://api.respan.ai/api/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.RESPAN_API_KEY}`,
  },
  body: JSON.stringify({
    model: "gpt-5.5",
    messages: [{ role: "user", content: "Say 'Hello World'" }],
  }),
});
console.log(await response.json());

Terminal


curl -X POST "https://api.respan.ai/api/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Verify

Open the Logs page to see your gateway requests captured as traces.

Switch models

Change the model parameter to use any supported provider through the same endpoint.

Python


response = requests.post(
    "https://api.respan.ai/api/chat/completions",
    headers=headers,
    json={"model": "gpt-5.5", "messages": messages},
)
response = requests.post(..., json={"model": "claude-sonnet-4-5-20250929", "messages": messages})
response = requests.post(..., json={"model": "gemini/gemini-3.5-flash", "messages": messages})

Browse the full model list to see all available models.

OpenAI-compatible parameters

All standard OpenAI chat completion parameters are supported.

Parameter	Type	Description
`messages`	`array`	List of messages in OpenAI format (`role` + `content`).
`model`	`string`	Model to use (e.g. `gpt-5.5`, `claude-sonnet-4-5-20250929`).
`stream`	`boolean`	Stream back partial progress token by token.
`temperature`	`number`	Controls randomness (0-2).
`max_tokens`	`number`	Maximum tokens to generate.
`top_p`	`number`	Nucleus sampling threshold.
`tools`	`array`	List of tools/functions the model may call.
`tool_choice`	`string\|object`	Controls tool selection.
`response_format`	`object`	Force JSON output.

Respan parameters

Pass Respan-specific parameters in the request body alongside OpenAI parameters. When using the OpenAI SDK, pass them via extra_body.

Observability

Parameter	Type	Description
`customer_identifier`	`string`	Tag to identify the user. See customer identifier.
`metadata`	`object`	Custom key-value pairs for filtering and search.
`custom_identifier`	`string`	Extra indexed tag (shows as “Custom ID” in spans).
`disable_log`	`boolean`	When `true`, only metrics are recorded.
`request_breakdown`	`boolean`	Returns a summarization of the response (tokens, cost, latency).

Reliability

Parameter	Type	Description
`fallback_models`	`array`	Models to try after `model` fails, for this request only.
`retry_params`	`object`	No effect on chat completions, which always use your organization’s retry settings. Applies only to `POST /api/responses`.

Caching

Parameter	Type	Description
`cache_enabled`	`boolean`	Enable response caching.
`cache_ttl`	`number`	How long a cached response is reused, in seconds. Without it, at most 30 minutes.
`cache_options`	`object`	Set `cache_by_customer: true` to scope cache per customer.

Credentials

Parameter	Type	Description
`customer_credentials`	`object`	Pass your customer’s provider API keys.
`credential_override`	`object`	One-off credential overrides for specific models.
`model_name_map`	`object`	Map default model names to custom Azure deployment names.

Prompt management

Parameter	Type	Description
`prompt`	`object`	Use a Respan-managed prompt template.

JSON


{
  "model": "gpt-5.5",
  "messages": [],
  "prompt": {
    "prompt_id": "your-prompt-id",
    "variables": {"user_name": "Sarah"}
  }
}

Response format

JSON


{
  "id": "chatcmpl-e1b9665b-c354-41c5-bbe5-178bd0b69773",
  "object": "chat.completion",
  "created": 1761546960,
  "model": "claude-sonnet-4-5-20250929",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "I'm doing well, thank you for asking!"
      }
    }
  ],
  "usage": {
    "completion_tokens": 20,
    "prompt_tokens": 2619,
    "total_tokens": 2639
  }
}