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

# Responses API

> Stateless Responses requests, streaming and function tool replay.

`POST /api/v1/responses` forwards native Responses requests through Portkey to the configured inference backend. Saved Portkey routing may select internally hosted models or OpenRouter/provider fallback. Model availability and optional capabilities are enabled only after model-specific compatibility and privacy tests pass. Requests remain native Responses throughout; there is no Responses-to-chat conversion. No server-managed response history is retained. Check `supports_responses` on `/api/v1/models` for enabled models.

> [!NOTE]
>
> Call `/api/v1/models` with your API key (`Authorization: Bearer YOUR_IO_API_KEY`) and select a model where `supports_responses` is `true`. Availability is account-specific during the restricted rollout. If no models have this flag enabled, your account does not currently have Responses access. Replace `ENABLED_MODEL` below with an enabled model ID from that list.

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_IO_API_KEY",
    base_url="https://api.intelligence.io.solutions/api/v1",
)
response = client.responses.create(
    model="ENABLED_MODEL", input="Explain token caching.", store=False,
)
print(response.output_text)
```

Set `stream=True` for Responses SSE events. Events carry increasing `sequence_number` values, stable item IDs and a native terminal completed/incomplete/failed response. There is no `[DONE]` sentinel.

## Supported contract

| Feature | Behavior |
| - | - |
| Input | String or text message items; system/developer/user/assistant roles; instructions |
| Functions | Flat function definitions, auto/none/required/named choice, parallel calls |
| Structured output | `text.format`: text, json\_object or json\_schema when supported |
| Reasoning | Native effort controls when enabled; native reasoning-item replay; engine-supported encrypted content |
| Usage | Input/output/total tokens; cached/reasoning tokens; cache writes only when measured |
| Advisory fields | Metadata, client\_metadata, user, safety\_identifier, prompt\_cache\_key, service\_tier, reasoning.summary and reasoning.context accepted but dropped; metadata returned empty, tier default |
| Stateless controls | `store:false`, no conversation or previous\_response\_id; truncation disabled |

## Tool loop / multiple turns

Clients resend previous input and output items, including exact function argument strings and call IDs. Tools execute in your application.

```python theme={null}
tools = [{"type": "function", "name": "weather",
          "parameters": {"type": "object", "properties": {
              "city": {"type": "string"}}, "required": ["city"]}}]
history = [{"role": "user", "content": "Weather in Paris?"}]
first = client.responses.create(model="ENABLED_MODEL", input=history,
                                tools=tools, tool_choice="required", store=False)
call = next(item for item in first.output if item.type == "function_call")
history += [item.model_dump(exclude_none=True) for item in first.output]
history += [{"type": "function_call_output", "call_id": call.call_id,
             "output": "Sunny, 20 C"}]
second = client.responses.create(model="ENABLED_MODEL", input=history,
                                 tools=tools, store=False)
```

Resolve every function call before replaying the next turn. `previous_response_id` is unsupported.

## Compatibility limits

Unsupported parameters/tools return HTTP 400 with an OpenAI-style error object. No retrieve/delete/cancel/input-items routes. Storage, background execution, automatic truncation, image/file/audio/video input, hosted/custom tools, stored prompts, routing extensions, reasoning enabled/budget controls, logprobs and text verbosity are unsupported. `include:["reasoning.encrypted_content"]` and native encrypted replay are forwarded; availability depends on the backend. No encryption is synthesized.

Accounts requiring storage receive HTTP 403. Unknown retention policy receives HTTP 503. Requests are limited to 2 MiB input, 128 tools/output items and 4 MiB upstream output. Explicit `max_output_tokens` values are capped at the model output limit; omitted values stay omitted. Transport has a 1800s total budget and streaming a 120s idle limit. After disconnect, the server keeps consuming within these bounds to collect measured usage. Missing or malformed required usage is never billed as zero. Billing persistence failures do not suppress completed output.

OpenAI `responses.create`/`responses.stream` and the OpenRouter benchmark harness are compatibility targets. Some clients require unsupported parameters, tools or state. Codex 0.160.1 function-tool mode is tested with the configuration below; hosted/custom/namespace tools remain unsupported. Engine versions differ in event and nullable-field behavior. A model that fails the SDK or harness checks remains disabled. Missing or malformed final usage cannot be treated as zero; an unexpected stream end emits an error rather than an invented completion.

Quota, context-limit and rate-limit errors retain actionable codes with sanitized messages; upstream authentication/routing failures return 502. Provider costs are not exposed in response usage. Stateless request handling does not certify downstream telemetry/storage retention.

See the [endpoint reference](/docs/reference/ai-models/create-response).

### Codex 0.160.1

Codex 0.160.1 function-tool mode works with the configuration below. Use a model enabled for Responses and function tools.

```toml theme={null}
model = "XiaomiMiMo/MiMo-V2.6-Flash"
model_provider = "io"
model_reasoning_effort = "none"
web_search = "disabled"

[agents]
enabled = false

[apps._default]
enabled = false

[model_providers.io]
name = "IO Intelligence"
base_url = "https://api.intelligence.io.solutions/api/v1"
env_key = "IO_API_KEY"
wire_api = "responses"
```

Set `IO_API_KEY` in your environment. App/agent namespaces and hosted search are disabled because this endpoint accepts function tools only. Other model presets and MCP plugins can introduce unsupported tools and need separate testing. Reasoning summary/context hints are accepted and ignored; Responses Lite behavior is not implemented.

Omit `max_output_tokens` to let the engine select its budget; explicit values are capped at the model output limit. `metadata` retains its 16-pair/64-character-key/512-character-value limits; `client_metadata` is discarded without these limits. The overall request limit is 2 MiB.

On models without reasoning enabled, `reasoning.effort="none"` is accepted and omitted upstream; active effort values remain unsupported. Unsupported tool errors include the tool type, Codex configuration keys and this guide link.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.