> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verlon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses API

> OpenAI-compatible Responses endpoint (client.responses.create)

Drop-in for `POST https://api.openai.com/v1/responses`. Point your OpenAI SDK's
`baseURL` at `https://api.verlon.ai/v1` and pass your Verlon gate id as `model`.
The request and response bodies match OpenAI's Responses API verbatim — the
Agents SDK and multi-turn tool loops with encrypted reasoning replay work
unmodified.

## Request

`POST /v1/responses`

| Field               | Type              | Notes                                                                                                             |
| ------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| `model`             | string            | Your Verlon **gate id** (routes to the gate's configured OpenAI model).                                           |
| `input`             | string \| item\[] | A prompt string, or an array of Responses items: `message`, `function_call`, `function_call_output`, `reasoning`. |
| `instructions`      | string            | System prompt.                                                                                                    |
| `tools`             | object\[]         | Flattened function tools (`{ type: 'function', name, parameters }`).                                              |
| `tool_choice`       | string \| object  | `auto` / `required` / `none` / `{ type: 'function', name }`.                                                      |
| `max_output_tokens` | number            | Output token cap.                                                                                                 |
| `reasoning`         | object            | `{ effort: 'low' \| 'medium' \| 'high' }` for reasoning models.                                                   |
| `stream`            | boolean           | Named-event SSE when `true`.                                                                                      |

<Warning>
  `store: true` and `previous_response_id` are **not supported** (Verlon is
  stateless — zero data retention by default). Echo prior `reasoning` and
  `function_call` items back in `input` each turn instead. Both return `400`.
</Warning>

## Reasoning replay

For reasoning models, Verlon automatically requests
`include: ['reasoning.encrypted_content']` and passes the encrypted reasoning
through untouched. To continue a tool loop, send the prior turn's `reasoning`
and `function_call` output items back at the front of `input`, followed by your
`function_call_output`:

```json theme={null}
{
  "model": "<gate-id>",
  "input": [
    { "role": "user", "content": "What's the weather in Tokyo?" },
    { "type": "reasoning", "id": "rs_…", "encrypted_content": "…" },
    { "type": "function_call", "call_id": "call_…", "name": "get_weather", "arguments": "{\"city\":\"Tokyo\"}" },
    { "type": "function_call_output", "call_id": "call_…", "output": "{\"temp_c\":22}" }
  ],
  "tools": [ /* … */ ]
}
```

## Restrictions

* **OpenAI-backed gates only.** A gate resolving to Anthropic, Google, or
  Mistral returns `400` — use [`/v1/chat/completions`](/api-reference/chat-completions)
  for cross-provider routing.
* Errors use OpenAI's nested shape (`{ error: { message, type, code, param? } }`).

See [OpenAI compatibility → Responses API](/provider-compatibility/openai#responses-api)
for SDK examples.