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

# Open Responses

> Use the Responses API with any LLM provider through Prisma AIRS AI Gateway — fully compliant with the Open Responses specification.

[Open Responses](https://www.openresponses.org/) is an open-source specification for multi-provider, interoperable LLM interfaces based on the OpenAI Responses API. It defines a shared schema for calling language models, streaming results, and composing agentic workflows — independent of provider.

**the AI Gateway is fully Open Responses compliant.** The Responses API works with every provider and model in the AI Gateway's catalog — including Anthropic, Gemini, Bedrock, and 60+ other providers that don't natively support it.

## Why Responses API

The Responses API is becoming the standard for agentic AI:

* **Agentic loops** — Models emit tool calls, receive results, and continue autonomously
* **Items as atomic units** — Clear state machines for context management
* **Semantic streaming** — Predictable, provider-agnostic streaming events
* **Unified tool calling** — Consistent function calling interface across all providers

Previously, the Responses API only worked with OpenAI. The AI Gateway extends it to all providers.

## Quick Start

Send a Responses API request to any provider. Change the `model` string -- the API format stays the same.

```sh cURL theme={"system"}
curl https://aigw.portkey.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PORTKEY_API_KEY" \
  -d '{
    "model": "@anthropic-provider/claude-sonnet-4-5-20250514",
    "input": "Explain quantum computing in simple terms"
  }'
```

> [!NOTE]
>
> The same code works for **any provider**. Switch the `@provider/model` string to use OpenAI, Gemini, Groq, Bedrock, or any of the 3,000+ supported models. See [Model Catalog](https://docs.portkey.ai/docs/aigw/product/model-catalog.md) for setup.

### Using the OpenAI SDK

Point the OpenAI SDK at the AI Gateway's base URL and `client.responses.create()` works unchanged:

```python OpenAI Python SDK theme={"system"}
from openai import OpenAI

client = OpenAI(
    api_key="PORTKEY_API_KEY",
    base_url="https://aigw.portkey.ai/v1"
)

response = client.responses.create(
    model="@anthropic-provider/claude-sonnet-4-5-20250514",
    input="Explain quantum computing in simple terms"
)

print(response.output_text)
```

```javascript OpenAI Node SDK theme={"system"}
import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: "PORTKEY_API_KEY",
    baseURL: "https://aigw.portkey.ai/v1"
});

const response = await client.responses.create({
    model: "@anthropic-provider/claude-sonnet-4-5-20250514",
    input: "Explain quantum computing in simple terms"
});

console.log(response.output_text);
```

## Text Generation

### Instructions (System Prompt)

Set a system prompt with `instructions` or pass a `system` role message in the `input` array. Both work identically.

```sh cURL theme={"system"}
curl https://aigw.portkey.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PORTKEY_API_KEY" \
  -d '{
    "model": "@anthropic-provider/claude-sonnet-4-5-20250514",
    "instructions": "You are a pirate. Always respond in pirate speak.",
    "input": "Say hello."
  }'
```

### Streaming

Enable streaming with `stream: true`.

```sh cURL theme={"system"}
curl https://aigw.portkey.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PORTKEY_API_KEY" \
  -d '{
    "model": "@anthropic-provider/claude-sonnet-4-5-20250514",
    "input": "Write a haiku about AI",
    "stream": true
  }'
```

The AI Gateway's adapter produces the same SSE event stream format (`response.created`, `response.output_text.delta`, `response.completed`, etc.) regardless of the underlying provider.

### Multi-turn Conversations

Pass previous messages in the `input` array for multi-turn conversations. Two formats are supported:

Supported roles: `user`, `assistant`, `developer` (maps to system), `system`, and `tool`.

### Generation Parameters

Control generation behaviour with optional parameters:

```sh cURL theme={"system"}
curl https://aigw.portkey.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PORTKEY_API_KEY" \
  -d '{
    "model": "@anthropic-provider/claude-sonnet-4-5-20250514",
    "input": "Write a creative story",
    "max_output_tokens": 2048,
    "temperature": 0.8,
    "top_p": 0.95
  }'
```

| Parameter | Type | Description |
| - | - | - |
| `max_output_tokens` | integer | Maximum tokens in the response. If not set, uses the provider's default |
| `temperature` | float | Sampling temperature (0-2). Higher = more creative |
| `top_p` | float | Nucleus sampling threshold (0-1) |
| `parallel_tool_calls` | boolean | Allow multiple tool calls in a single response (default: `true`) |
| `user` | string | End-user identifier for abuse tracking |
| `metadata` | object | Arbitrary metadata to attach to the response |

## Tool Calling

Define tools with the Responses API `function` tool format. Works across all providers that support function calling.

```sh cURL theme={"system"}
curl https://aigw.portkey.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PORTKEY_API_KEY" \
  -d '{
    "model": "@anthropic-provider/claude-sonnet-4-5-20250514",
    "input": "What'\''s the weather in San Francisco?",
    "tools": [{
      "type": "function",
      "name": "get_weather",
      "description": "Get current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "City name"}
        },
        "required": ["location"]
      }
    }]
  }'
```

### Tool Choice

Control tool usage with `tool_choice`:

| Value | Behaviour |
| - | - |
| `"auto"` | Model decides whether to call a tool (default) |
| `"none"` | Model will not call any tools |
| `"required"` | Model must call at least one tool |
| `{"type": "function", "name": "get_weather"}` | Force a specific tool |

### Function Call Results

Return function call results in a multi-turn flow with `function_call` and `function_call_output` items:

## Input Types

### Vision

Send images with the `input_image` content type. The optional `detail` parameter (`"high"`, `"low"`, `"auto"`) controls processing fidelity.

### File Inputs

Send files with the `input_file` content type. Pass file data as a base64-encoded data URL or reference an existing file by `file_id`.

## Structured Output

Control output format with `text.format`. Supports `json_schema` for strict structured output and `json_object` for free-form JSON.

### JSON Schema

### JSON Object

For free-form JSON output without a strict schema:

## Reasoning and Thinking

Control reasoning with the unified `reasoning` parameter. The AI Gateway maps this to each provider's native thinking mechanism automatically.

### Reasoning Effort

`reasoning.effort` controls how much the model reasons before responding. Works across OpenAI, Anthropic, and Gemini — the AI Gateway translates to each provider's native format.

The AI Gateway maps `reasoning.effort` to each provider's native thinking configuration:

> **Anthropic — maps to thinking.budget\_tokens**
>
> | Effort | Budget Tokens |
> | - | - |
> | `low` | 1,024 |
> | `medium` | 8,192 |
> | `high` | 16,384 |
> | `xhigh` | 32,768 |

> **Gemini 2.5 — maps to thinking\_config.thinking\_budget**
>
> | Effort | Budget Tokens |
> | - | - |
> | `low` | 1,024 |
> | `medium` | 8,192 |
> | `high` | 24,576 |

> **OpenAI o-series**
>
> Passed through as `reasoning_effort` natively. No translation needed.

### Anthropic Extended Thinking

For fine-grained control over Anthropic's extended thinking, pass the `thinking` parameter directly with an exact `budget_tokens` value. This takes precedence over `reasoning.effort` if both are set.

## Prompt Caching

Enable prompt caching with `cache_control` on content items and tools. Works with Anthropic and other compatible providers.

Cache control also works on tool definitions:

```python Python theme={"system"}
tools=[{
    "type": "function",
    "name": "search",
    "description": "Search the knowledge base",
    "parameters": {"type": "object", "properties": {"query": {"type": "string"}}},
    "cache_control": {"type": "ephemeral"}
}]
```

## Using with AI Gateway Features

The Responses API works with all AI Gateway features.

> **[Configs](https://docs.portkey.ai/docs/aigw/product/ai-gateway/configs.md)**
>
> Route, load balance, and set fallbacks

> **[Caching](https://docs.portkey.ai/docs/aigw/product/ai-gateway/cache-simple-and-semantic.md)**
>
> Cache responses for faster, cheaper calls

> **[Guardrails](https://docs.portkey.ai/docs/aigw/product/guardrails.md)**
>
> Input/output guardrails

> **[Observability](https://docs.portkey.ai/docs/aigw/product/observability.md)**
>
> Full logging and tracing

Pass features through headers or the config parameter:

```sh cURL theme={"system"}
curl https://aigw.portkey.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PORTKEY_API_KEY" \
  -H "x-portkey-config: pp-config-xxx" \
  -d '{
    "model": "@anthropic-provider/claude-sonnet-4-5-20250514",
    "input": "Hello!"
  }'
```

## Provider Support

The AI Gateway handles the Responses API in two ways depending on the provider:

* **Native providers** — Requests pass through directly to the provider's Responses API endpoint
* **Adapter providers** — the AI Gateway automatically translates between Responses API and Chat Completions formats

This translation is transparent — the response format is identical regardless of which provider handles the request.

**Native providers:** OpenAI, Azure OpenAI, Grok (x.ai), Groq, OpenRouter, Azure AI, Perplexity AI

**Adapter providers:** Anthropic, Google Gemini, Google Vertex AI, AWS Bedrock, Mistral AI, Together AI, and [all other providers](https://docs.portkey.ai/docs/integrations.md)

All features documented on this page — text generation, streaming, tool calling, reasoning, vision, structured output, prompt caching, and multi-turn conversations — work with both native and adapter providers.

### Native-Only Features

A few features require server-side state and are limited to native providers:

* **`previous_response_id`** — Use [multi-turn conversations](#multi-turn-conversations) to pass history in the `input` array instead
* **`store`** — Silently ignored on adapter providers; responses are not persisted server-side
* **Retrieve / Delete** — `GET` and `DELETE` on `/v1/responses/:id` are not available
* **Built-in tools** — `web_search`, `file_search`, `computer_use` are native-only. Use [Remote MCP](https://docs.portkey.ai/docs/aigw/product/ai-gateway/remote-mcp.md) or custom function tools instead

Everything else — text generation, streaming, instructions, tool calling, structured output, reasoning, vision, file inputs, prompt caching, and multi-turn conversations — works with **every provider**.

## Reference

### Supported Parameters

Complete list of parameters supported by the Responses API and how they map internally:

| Responses API Parameter | Chat Completions Equivalent | Notes |
| - | - | - |
| `input` | `messages` | String, message array, or typed input items |
| `instructions` | System message (prepended) | Added as the first message with `role: system` |
| `model` | `model` | Use `@provider/model` format or set provider via headers |
| `stream` | `stream` | SSE events are translated to Responses API format |
| `max_output_tokens` | `max_tokens` | Only sent if explicitly set |
| `temperature` | `temperature` | Direct mapping |
| `top_p` | `top_p` | Direct mapping |
| `tools` | `tools` | Only `function` type is supported |
| `tool_choice` | `tool_choice` | `auto`, `none`, `required`, or specific function |
| `parallel_tool_calls` | `parallel_tool_calls` | Direct mapping |
| `text.format` | `response_format` | `json_schema` and `json_object` supported |
| `reasoning.effort` | Provider-specific | Mapped to thinking for Anthropic/Gemini, `reasoning_effort` for OpenAI |
| `thinking` | `thinking` | Anthropic-specific passthrough |
| `top_logprobs` | `top_logprobs` | Direct mapping |
| `user` | `user` | Direct mapping |
| `metadata` | `metadata` | Direct mapping |

> **Input Content Types**
>
> | Content Type | Description |
> | - | - |
> | `input_text` | Text content (maps to `text` in Chat Completions) |
> | `input_image` | Image URL with optional `detail` parameter |
> | `input_file` | File with `filename` and `file_data` (base64 data URL) or `file_id` |
> | `function_call` | Tool call record with `name`, `call_id`, and `arguments` |
> | `function_call_output` | Tool result with `call_id` and `output` |

> **Response Output Types**
>
> | Output Type | Description |
> | - | - |
> | `message` | Text response with `output_text` content |
> | `function_call` | Tool call with `name`, `call_id`, `arguments`, and `status` |
> | `reasoning` | Thinking/reasoning content with `summary` array (from providers that support it) |

### API Endpoints

* [Create a Response](https://docs.portkey.ai/docs/aigw/api-reference/responses/create-response.md) -- `POST /v1/responses`
* [Retrieve a Response](https://docs.portkey.ai/docs/aigw/api-reference/responses/get-response.md) -- `GET /v1/responses/{response_id}`
* [Delete a Response](https://docs.portkey.ai/docs/aigw/api-reference/responses/delete-response.md) -- `DELETE /v1/responses/{response_id}`
* [List Input Items](https://docs.portkey.ai/docs/aigw/api-reference/responses/list-input-items.md) -- `GET /v1/responses/{response_id}/input_items`

> **[Open Responses Spec](https://www.openresponses.org/specification)**
>
> Full specification

> **[API Reference](https://docs.portkey.ai/docs/aigw/api-reference/responses/create-response.md)**
>
> Responses API reference

> **[Remote MCP](https://docs.portkey.ai/docs/aigw/product/ai-gateway/remote-mcp.md)**
>
> MCP via Responses API

> **[Universal API](https://docs.portkey.ai/docs/aigw/product/ai-gateway/universal-api.md)**
>
> All three API formats

> **[Messages API](https://docs.portkey.ai/docs/aigw/product/ai-gateway/messages-api.md)**
>
> Anthropic Messages format

> **[Chat Completions](https://docs.portkey.ai/docs/aigw/product/ai-gateway/chat-completions.md)**
>
> OpenAI Chat Completions format


## Related topics

- [gRPC (Beta)](https://docs.portkey.ai/docs/aigw/product/ai-gateway/grpc.md)
- [OpenAI](https://docs.portkey.ai/docs/aigw/integrations/llms/openai.md)
- [OpenAI Codex](https://docs.portkey.ai/docs/aigw/integrations/libraries/codex.md)
- [OpenAI Swarm](https://docs.portkey.ai/docs/aigw/integrations/agents/openai-swarm.md)
- [Strict OpenAI Compliance](https://docs.portkey.ai/docs/aigw/product/ai-gateway/strict-open-ai-compliance.md)


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