> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Respan API (gateway)

> Set up Respan API with the Respan gateway.

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

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

> **Note**
>
> `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.

> **Note**
>
> **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](https://platform.respan.ai/platform/gateway/api-keys).

## Setup

#### Install packages

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

```bash
pip install requests
```

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

#### Make a request

**`Python`**

```python 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`**

```typescript 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());
```

**`cURL`**

```bash cURL
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](https://platform.respan.ai/platform/requests) 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](https://platform.respan.ai/platform/models) to see all available models.

## OpenAI-compatible parameters

All standard [OpenAI chat completion parameters](/docs/apis/gateway/create-chat-completion#openai-compatible-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](/docs/documentation/features/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`  | Backup models ranked by priority.                                                                                                                                          |
| `load_balance_group` | `object` | `{"group_id": "..."}` of a saved load balancing group. The picked model replaces `model`.                                                                                  |
| `retry_params`       | `object` | No effect on chat completions, which always use your organization's [retry settings](/docs/documentation/features/gateway/retries). 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
  }
}
```