Responses API

Q: How do I get JSON output from the Responses API?

Use Structured Outputs: set text.format to json_schema with your schema and strict: true, and the model's answer will always match it.

The Responses API is OpenAI's recommended endpoint for new projects, combining model calls, built-in tools, structured outputs and conversation state in one request. Chat Completions is still supported, and the Assistants API it replaced shut down on Aug 26, 2026.

The Responses API (POST /v1/responses) is the endpoint OpenAI says is "recommended for all new projects": one call can reason, use built-in tools such as web search and file search, return JSON that matches your schema, and carry the conversation forward without you resending the history. It launched on Mar 11, 2025 alongside the Agents SDK. Chat Completions, the older endpoint, "is still supported", but on the GPT-6 models tool calls work only through Responses (latest model guide). The Assistants API, which once held threads and tools on OpenAI's servers, shut down on Aug 26, 2026. For the API as a whole, see OpenAI API.

Quick facts

Endpoint	`POST /v1/responses`
Released	Mar 11, 2025
Status	Recommended for all new projects, as of Nov 6, 2026
Built-in tools	Web search, file search, code interpreter, hosted shell, remote MCP, computer use, image generation, tool search, skills
State	`store: true`, `previous_response_id`, or the Conversations API (Aug 20, 2025)
Transport	HTTP, streaming, and a WebSocket mode since Feb 23, 2026
Chat Completions	Still supported; no tool calls on GPT-6 Astra, Sol, Terra
Assistants API	Shut down Aug 26, 2026

Responses vs Chat Completions

Both endpoints call the same models and bill at the same token prices. The differences are in what one request can do (migration guide, read Nov 6, 2026):

	Responses API	Chat Completions
Output	A typed `output` array (messages, tool calls and other items)	One message per choice
Built-in tools	Yes, several in one request	No; only your own functions
Agentic loop	The model can call several tools before answering	One step per call
State on OpenAI's side	`store: true`, `previous_response_id`, Conversations	None; you resend the history
Encrypted reasoning for Zero Data Retention	Yes	Not listed
Several answers at once (`n`)	Not offered	Offered
GPT-6 tool calls	Required	Not accepted with tools

OpenAI reports two benefits from its own internal tests: a 3% gain on SWE-bench with reasoning models, and 40% to 80% better cache use (migration guide). These are OpenAI's figures, not independent measurements.

When Chat Completions still makes sense: existing code that works, plain text generation with no tools, and libraries or other providers that speak only the Chat Completions format. OpenAI has not announced a shutdown date for it as of Nov 6, 2026 (the deprecations page lists none).

How to call the Responses API

Install the SDK (pip install openai or npm install openai) and set OPENAI_API_KEY (quickstart).
Call responses.create with a model and an input.
Read the result from the output array; tool calls arrive as their own items.
To continue the conversation, pass the earlier response's id as previous_response_id, or attach a Conversation.

from openai import OpenAI

client = OpenAI()
first = client.responses.create(
    model="gpt-6.1-sol",
    input="Summarize the main idea of the Responses API in one sentence.",
)
follow_up = client.responses.create(
    model="gpt-6.1-sol",
    previous_response_id=first.id,
    input="Now say it for a ten-year-old.",
)

Built-in tools

The GPT-6 model pages list these tools for the Responses API: web search, file search, image generation, code interpreter, hosted shell, apply patch, skills, computer use, MCP and tool search (GPT-6 Astra). They arrived over 18 months:

Mar 11, 2025: web search, file search and computer use (changelog).
May 20, 2025: remote MCP servers and code interpreter.
Aug 21, 2025: connectors as MCP wrappers.
Feb 10, 2026: Skills, the Hosted Shell tool and server-side compaction.
Mar 5, 2026: tool search and generally available computer use, with GPT-5.4. Tool search works only in Responses and only with GPT-5.4 and later (tools guide).

Tools have their own prices: web search costs $10 per 1,000 calls plus content tokens, file search $2.50 per 1,000 calls, and containers for the shell and code interpreter from $0.03 per 20-minute session. See OpenAI API Pricing.

Function calling

0:52 Your own functions are declared as tools with a JSON Schema; the model returns a function call item, your code runs it, and you send the result back. Three later additions changed how that works (changelog):

Custom tools and minimal reasoning came with GPT-5 on Aug 7, 2025.
Programmatic Tool Calling came with GPT-5.6 on Jul 9, 2026: the model writes JavaScript that orchestrates several tool calls. It is on by default in the Agents API (tools guide).
Async tool calling came with GPT-6 Astra on Sep 3, 2026: a tool marked async: true lets the model carry on and receive the result later by its call_id (latest model guide).

2:34 GPT-6 also added mid-turn steering over the WebSocket mode and configuration_update items that change the reasoning effort mid-conversation without losing the prompt cache (latest model guide).

Structured outputs

Structured Outputs makes the model's answer always match a JSON Schema you supply. In the Responses API you set text.format to type json_schema with strict: true (structured outputs guide). It works from the GPT-4o snapshots of 2024 onward. The older JSON mode only promises valid JSON, not your schema, so OpenAI's guide steers new work to Structured Outputs.

Long conversations and compaction

Server-side compaction (Feb 10, 2026) and the /responses/compact endpoint (Dec 11, 2025) shrink long histories so an agent can keep working past the context window (changelog). The GPT-6 models have a 1,050,000-token context window, but prompts over 272K tokens pay long-context prices.

The Assistants API (retired)

The Assistants API kept assistants, threads, files and runs on OpenAI's servers. Its v1 beta ended on Dec 18, 2024; OpenAI announced the end of the whole API on Aug 26, 2025 and switched it off on Aug 26, 2026. The replacement is the Responses API, with the Conversations API in place of threads (deprecations). The migration guide says it "is no longer available" (migration guide).

Reusable prompts (v1/prompts), a Responses feature that stored prompt templates in the dashboard, also shut down on Nov 30, 2026.

Open Responses and other providers

OpenAI announced the Open Responses spec on Jan 15, 2026, and Amazon Bedrock serves GPT-5.4 and GPT-5.5 through a Responses-compatible endpoint since Jun 1, 2026. Which other providers implement the spec was not checked for this page.

For agent frameworks built on top of Responses, see Agents SDK. For speech, see Realtime API.

Frequently asked questions

What is the OpenAI Responses API? It is OpenAI's main API endpoint for generating model output, released Mar 11, 2025, which combines text generation, built-in tools, structured outputs and stored conversation state in one request. OpenAI recommends it for all new projects.

Is Chat Completions deprecated? No. As of Nov 6, 2026 OpenAI says Chat Completions is still supported and lists no shutdown date, but GPT-6 Astra, Sol and Terra need the Responses API for tool calls.

When did the Assistants API shut down? OpenAI shut down the Assistants API on Aug 26, 2026, a year after announcing it. Its replacement is the Responses API together with the Conversations API.

Does the Responses API cost more than Chat Completions? No. Both bill the same per-token model prices; the Responses API adds charges only when you use a paid built-in tool, such as web search at $10 per 1,000 calls.

How do I get JSON output from the Responses API? Use Structured Outputs: set text.format to json_schema with your schema and strict: true, and the model's answer will always match it.