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

# Responses API

> Create model responses with built-in tools, server-side conversation state, and multimodal input through the AI Gateway. Compare the Responses API with Chat Completions.

**Use Cases**

<AccordionGroup>
  <Accordion title="Use built-in server-side tools">
    Use web search and other built-in tools without client-side tool orchestration.
  </Accordion>

  <Accordion title="Retain server-side conversation state">
    Server-side state is retained between turns via `previous_response_id`, without resending the full message history.
  </Accordion>

  <Accordion title="Send multimodal input">
    Pass `input_image` and `input_file` items in a single request.
  </Accordion>

  <Accordion title="Build agent-style workflows">
    Combine function calling, reasoning, and tool continuation for agent-style loops.
  </Accordion>
</AccordionGroup>

***

The **Responses API** is the OpenAI-style `/responses` endpoint on the **AI Gateway**, exposed at [`POST /v3/router/responses`](/reference/responses/create-response). It implements the [OpenResponses](https://www.openresponses.org/) specification: a request carries a `model` and an `input`, and the response returns structured `output` items together with token and cost usage. The endpoint supports built-in tools such as web search, server-side conversation state, streaming, and multimodal input. Choose it when those capabilities matter; for a classic messages-based flow, use [Chat Completions](/docs/ai-gateway/features/openai-compatible-api).

<Note>
  Invoke a configured agent by setting `model` to `agent/<key>`; the agent's tools, knowledge bases, and memory apply automatically. See [Run Agents](/docs/ai-studio/ai-engineering/run-agents).
</Note>

## Responses vs Chat Completions

Both endpoints share the same base URL (`https://api.orq.ai/v3/router`), authentication, and **AI Gateway** features: [fallbacks](/docs/ai-gateway/features/retries#fallbacks), [retries](/docs/ai-gateway/features/retries), [caching](/docs/ai-gateway/features/cache), [guardrails](/docs/ai-gateway/configuration/guardrails), and [budgets](/docs/ai-gateway/budgets). The table below lists the differences.

| Consideration      | Responses API ([`POST /v3/router/responses`](/reference/responses/create-response))               | Chat Completions ([`POST /v3/router/chat/completions`](/reference/chat/create-chat-completion)) |
| ------------------ | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Built-in tools     | Supported. Web search (`web_search`, `web_search_preview`) is Responses-only                      | Not supported                                                                                   |
| Conversation state | Server-side: `previous_response_id` continues from a stored response (`store` defaults to `true`) | Client-side: resend the full message history each turn                                          |
| Multimodal input   | `input` items: `input_text`, `input_image`, `input_file`                                          | `messages` content: `text`, `image_url`, `file`                                                 |
| Reasoning controls | [`reasoning` object](/docs/ai-gateway/features/reasoning) for OpenAI models                       | `reasoning_effort` (OpenAI) and `thinking` (Anthropic, Google Gemini)                           |
| Streaming events   | `response.output_text.delta` and other response events                                            | `choices[0].delta.content`                                                                      |
| Output shape       | Item-based `output` array with the `output_text` helper                                           | `choices[0].message`                                                                            |

Function calling works on both endpoints through the `tools` array; see [Tool Calling](/docs/ai-gateway/features/tool-calling).

## Quick Start

Use the OpenAI SDK against the **AI Gateway** base URL and call `client.responses.create`.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.orq.ai/v3/router/responses \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.6-sol",
      "input": "What is the capital of France?"
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await client.responses.create({
    model: "openai/gpt-5.6-sol",
    input: "What is the capital of France?",
  });

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

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  response = client.responses.create(
      model="openai/gpt-5.6-sol",
      input="What is the capital of France?",
  )

  print(response.output_text)
  ```
</CodeGroup>

## Statefulness

Responses are persisted server-side by default (`store` defaults to `true`) and can be retrieved by ID (`GET /v3/router/responses/{response_id}`, see [Retrieve Response](/reference/responses/retrieve-response)). Continue a conversation by passing `previous_response_id` on the next request; the gateway uses the stored conversation instead of requiring the full history again. `previous_response_id` requires `store: true` on the original response.

<Note>
  Set `store: false` to skip persisting a response. The response cannot be retrieved later, and `previous_response_id` will not work on follow-up requests.
</Note>

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # First turn. The response ID is returned as "id" in the response body.
  curl -X POST https://api.orq.ai/v3/router/responses \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.6-sol",
      "input": "My name is Ada and I am writing a book about AI."
    }'

  # Continue the conversation from the stored response.
  curl -X POST https://api.orq.ai/v3/router/responses \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.6-sol",
      "previous_response_id": "resp_01KP6DFXWPKZ12AS254R4W6C08",
      "input": "What is the title of my book?"
    }'

  # Retrieve the stored response by ID.
  curl https://api.orq.ai/v3/router/responses/resp_01KP6DFXWPKZ12AS254R4W6C08 \
    -H "Authorization: Bearer $ORQ_API_KEY"
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.ORQ_API_KEY,
    baseURL: "https://api.orq.ai/v3/router",
  });

  const first = await client.responses.create({
    model: "openai/gpt-5.6-sol",
    input: "My name is Ada and I am writing a book about AI.",
  });

  const followUp = await client.responses.create({
    model: "openai/gpt-5.6-sol",
    previous_response_id: first.id,
    input: "What is the title of my book?",
  });

  const retrieved = await client.responses.retrieve(first.id);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from openai import OpenAI
  import os

  client = OpenAI(
      api_key=os.environ.get("ORQ_API_KEY"),
      base_url="https://api.orq.ai/v3/router",
  )

  first = client.responses.create(
      model="openai/gpt-5.6-sol",
      input="My name is Ada and I am writing a book about AI.",
  )

  follow_up = client.responses.create(
      model="openai/gpt-5.6-sol",
      previous_response_id=first.id,
      input="What is the title of my book?",
  )

  retrieved = client.responses.retrieve(first.id)
  ```
</CodeGroup>

## Streaming

Set `"stream": true` on the request body. The server responds with a Server-Sent Events stream in the OpenAI Responses format: incremental text arrives as `response.output_text.delta` events, and the stream ends with a completed event carrying final usage. See [Streaming](/docs/ai-gateway/features/streaming) for event handling, retry, and error patterns.

## Built-in tools

Built-in tools run server-side: pass them in the `tools` array and the gateway executes them during generation. Web search is available only through the Responses API, as `web_search` and `web_search_preview` tool types. See [Web search in Responses API](/docs/ai-gateway/features/web-search) for tool fields, provider mapping, and the `include` option.

Function tools work on both endpoints; see [Tool Calling](/docs/ai-gateway/features/tool-calling).

## Multimodal input

Send images and PDFs alongside text in the `input` array using `input_image` and `input_file` items. See [Multimodal inputs and generation](/docs/ai-gateway/features/multimodal) for supported formats and full examples.

## AI Gateway features

All **AI Gateway** features apply to the Responses API. Most are configured per request through request-body fields; budgets are configured in the console and apply by scope.

| Feature          | How it applies                                                               | Request field            | Docs                                                             |
| ---------------- | ---------------------------------------------------------------------------- | ------------------------ | ---------------------------------------------------------------- |
| Fallbacks        | Try a fallback model when the primary fails                                  | `fallbacks`              | [Retries](/docs/ai-gateway/features/retries)                     |
| Retries          | Automatic retries on configured status codes                                 | `retry`                  | [Retries](/docs/ai-gateway/features/retries)                     |
| Response caching | Exact-match cache with TTL control                                           | `cache`, `cache_control` | [Cache](/docs/ai-gateway/features/cache)                         |
| Guardrails       | LLM and Python evaluators on requests and responses                          | `guardrails`             | [Guardrails](/docs/ai-gateway/configuration/guardrails)          |
| Budgets          | Spending limits by workspace, project, identity, API key, provider, or model | —                        | [Budgets](/docs/ai-gateway/budgets)                              |
| Load balancing   | Distribute requests across models                                            | `load_balancer`          | [Load Balancing](/docs/ai-gateway/features/load-balancing)       |
| Plugins          | PII redaction transforms on request and response text                        | `plugins`                | [PII Redaction](/docs/ai-gateway/features/plugins/pii-redaction) |
| Trace masking    | Mask request and response data in stored traces                              | `security`               | [Security](/docs/ai-gateway/features/security)                   |
| Threads          | Group related requests in observability                                      | `thread`                 | [Thread Management](/docs/ai-gateway/thread-management)          |

## See also

* [Create Response](/reference/responses/create-response): full request and response reference
* [Retrieve Response](/reference/responses/retrieve-response): fetch a stored response by ID
* [OpenAI-Compatible API](/docs/ai-gateway/features/openai-compatible-api): base URL and all supported endpoints
* [Run Agents](/docs/ai-studio/ai-engineering/run-agents): invoke a configured agent through the Responses API
* [Reasoning](/docs/ai-gateway/features/reasoning): `reasoning` effort for OpenAI models via the Responses API
* [Using Prompts](/docs/ai-gateway/features/using-prompts): template variables and prompt substitution
* [Memory stores](/docs/ai-studio/ai-engineering/memory-stores): persistent memory across requests with the `memory` field