Response API Explained: The Next-Gen Model Interface

The Response API is OpenAI’s next-generation model interface, purpose-built for stateful, multi-turn, tool-orchestrated AI applications. Compared to the classic Chat Completions API, it unifies conversation state, tool calls, reasoning, and multimodal input into a simpler and more powerful programming model.

What is the Response API

The Response API (/v1/responses) is the unified model endpoint OpenAI shipped in 2025. It consolidates capabilities that used to be spread across Chat Completions, Assistants, and Tools into a single call, so a single request can handle:

Multi-turn conversation and context management
Built-in tools (web search, file search, code interpreter, computer use)
Custom function calling
Reasoning traces from reasoning models (the o-series)
Multimodal input and output (text, images, audio)

Key differences from Chat Completions

Stateful vs stateless

Chat Completions requires you to resend the full history on every request. The Response API lets you continue from the last response via previous_response_id, and manages context server-side.

Unified input

Chat Completions uses a messages array. The Response API uses a single input field that accepts a string, a message array, or a multimodal payload with images and files.

Built-in tools

The Response API natively supports hosted tools such as web_search, file_search, code_interpreter, and computer_use, so you no longer need to build them yourself.

Transparent reasoning

For reasoning models like o1 and o3, the Response API returns explicit reasoning items in the output, making the chain of thought easy to inspect and debug.

The simplest possible call

cURL

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": "Explain quantum entanglement in one sentence."
  }'

Key fields in the response:

id: unique ID for this response, usable to continue the conversation
output: array of items the model produced (text, tool calls, reasoning)
output_text: convenience field with all text items concatenated
usage: token accounting

Multi-turn conversations without manual history

The old pattern required resending the full messages array every turn. With the Response API you just pass the previous id:

Python

from openai import OpenAI

client = OpenAI()

first = client.responses.create(
    model="gpt-4.1",
    input="Recommend three science-fiction novels."
)

second = client.responses.create(
    model="gpt-4.1",
    previous_response_id=first.id,
    input="Which one is the shortest, and roughly how long is it?"
)

print(second.output_text)

The server automatically threads in the previous context, so the client is simpler and you avoid paying for repeated tokens.

Built-in tools: web search in one line

Python

response = client.responses.create(
    model="gpt-4.1",
    tools=[{"type": "web_search"}],
    input="Who won the 2026 Nobel Prize in Physics?"
)

print(response.output_text)

You don’t need to run a search service, scrape pages, or stitch citations together. The model decides when to search and how to weave results into its answer. file_search (RAG over uploaded files), code_interpreter (sandboxed execution), and computer_use (browser and desktop control) work the same way.

Streaming output

The Response API streams structured Server-Sent Events, which is easier to consume than Chat Completions’ raw deltas:

Python

stream = client.responses.create(
    model="gpt-4.1",
    input="Write a short poem about autumn.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Common event types include response.created, response.output_text.delta, response.tool_call.created, and response.completed.

When to use the Response API

Good fits for the Response API

Building agents or multi-step task flows
Needing hosted tools like web search, file search, or code execution
Using reasoning models (o1, o3) and wanting to inspect the chain of thought
Wanting to simplify multi-turn state management

Reasons to stay on Chat Completions for now

You have a large codebase built on messages and no immediate migration payoff
You only need stateless, one-shot completions with no tools
You depend on a third-party wrapper that hasn’t adopted the Response API yet

Migration guide

Swap the endpoint

Replace /v1/chat/completions with /v1/responses and rename messages to input.

Manage sessions with previous_response_id

Stop persisting full histories on the client. Keep only the most recent response.id.

Adopt built-in tools

Evaluate whether your custom search, RAG, or code execution can be replaced with web_search, file_search, or code_interpreter.

Migrate the event stream

If you use streaming, switch delta parsing to a dispatch based on event.type.

Summary

The Response API collapses model, tools, state, and multimodality into a single interface, and it’s OpenAI’s recommended entry point for the agent era. Start new projects on it directly; migrate existing ones feature by feature, prioritizing the complexity savings from hosted tools and server-side state.

Getting Started

Guides

Response API Explained: The Next-Gen Model Interface

What is the Response API

Key differences from Chat Completions

Stateful vs stateless

Unified input

Built-in tools

Transparent reasoning

The simplest possible call

Multi-turn conversations without manual history

Built-in tools: web search in one line

Streaming output

When to use the Response API

Migration guide

Summary

​What is the Response API

​Key differences from Chat Completions

Stateful vs stateless

Unified input

Built-in tools

Transparent reasoning

​The simplest possible call

​Multi-turn conversations without manual history

​Built-in tools: web search in one line

​Streaming output

​When to use the Response API

​Migration guide

​Summary

What is the Response API

Key differences from Chat Completions

The simplest possible call

Multi-turn conversations without manual history

Built-in tools: web search in one line

Streaming output

When to use the Response API

Migration guide

Summary