OpenAI Responses API

The one OpenAI now points new work at

OpenAI has two general-purpose endpoints. Chat Completions is the one the whole ecosystem copied. Responses is the newer one, and the migration guide is unambiguous about which to pick:

While Chat Completions remains supported, Responses is recommended for all new projects.

POST /v1/responses rather than POST /v1/chat/completions. Existing code does not have to move; new code has little reason not to.

Input, and the instruction that sits outside it

Chat Completions takes a messages array, and a system instruction is the first entry in it. Responses splits those:

• input: a string, or an array of typed items
• instructions: the standing instruction, as its own top-level parameter

A string input is the shortest useful request anyone has shipped: no array, no role, no content block.

The split matters for the same reason it matters in the Claude Messages API, which made the same choice: an instruction that governs the whole exchange is not a turn in it, and keeping it out of the transcript stops it drifting as the conversation grows.

One behavior to know before you rely on it: previous_response_id does not carry the previous response's top-level instructions forward. Resend stable instructions on each request.

Output is a typed array, not a string

Chat Completions returns choices[0].message.content. Responses returns an output array of typed items, with an output_text helper in the SDK for when all you want is the text.

The helper is a convenience, not the shape. Reaching for output_text on a response that also contains a tool call or a built-in tool's result gives you the text and silently drops the rest. This is the same trap that indexing content[0] sets in the Messages API: it works until the day the first item is not what you assumed.

Read the array when the model can do more than talk.

State the server keeps

Responses are stored by default. Set store: false to turn that off.

Given storage, a multi-turn conversation has two shapes:

Chain by reference. Pass previous_response_id and the server supplies the prior context. Your request carries only the new input.

Carry it yourself. Pass the prior output items back in the next input, the way Chat Completions requires.

The first is less to send and less to store. The trade is that the conversation now lives on OpenAI's side, which is a data question before it is an engineering one: if you turn storage off, previous_response_id is not available to you and you are carrying the transcript.

Neither removes the cost that state and historical context describes. A referenced conversation is still a growing prefix; you are not the one transmitting it.

Tools that run on the server

The clearest reason to prefer Responses is the tools you do not implement. It ships native access to web search, file search, computer use, code interpreter and remote MCP servers. On Chat Completions those are function definitions you write and execute.

That is a real shift in where the work sits. A web search on Chat Completions means declaring a tool, receiving the call, running the search, and returning the result. On Responses it is a tool you enable.

The trade is the usual one for a managed capability: less code, less control over how it runs, and a dependency on the provider's version of the behavior. Whether that is a good deal depends on how specific your requirements are, which is the same question tools and function calling asks about tools you write yourself.

What migrating involves

For a straightforward text call, little:

OpenAI also reports better cache utilization on Responses than on Chat Completions, which is a claim about their infrastructure rather than something measurable from outside. Treat it as a reason to look at your own cache figures after moving rather than as a number to put in a plan.

Further reading

• OpenAI, Migrate to the Responses API: the recommendation, the parameter mapping, and the built-in tools.
• OpenAI-compatible APIs: why the older endpoint is the one everyone else implements.
• Claude Messages API: the same instruction-outside-the-transcript decision, made independently.
• State and historical context: what a conversation costs whichever side stores it.