The OpenAI Responses API is the way OpenAI now wants every new project to call its models: it's the successor to Chat Completions, with built-in tools like web search and file search and a loop that lets the model call several tools in one request. Chat Completions still works, but OpenAI's migration guide says Responses "is recommended for all new projects", and the older Assistants API was switched off on August 26, 2026.
If a developer has told you "we need to move to Responses" and you nodded along, this page is the plain version. For background on the API as a whole, start with my plain-English guide to the OpenAI API. Here I'm sticking to what changes, what it costs you in effort, and the traps OpenAI's own docs warn about.
Why OpenAI is steering new work to Responses
OpenAI calls Responses its new API primitive, an evolution of Chat Completions. In practice it adds:
- Built-in tools: web search, file search, computer use, code interpreter and remote MCP servers, without writing your own integration for each.
- An agentic loop by default: the model can call several tools, plus your own functions, inside a single request.
- Stateful conversations: with storage on, context carries from turn to turn, or you can chain responses together.
- Flexible inputs: a plain string, or a list of messages plus top-level instructions.
- Encrypted reasoning: reasoning without storing state, for organisations that can't keep data with OpenAI.
OpenAI's own tests report better results from reasoning models and better cache use on Responses. The stronger push is the models. The guide says GPT-6 Astra and GPT-6.1 Sol require the Responses API for tool calling, and that starting with GPT-5.4, Chat Completions doesn't support tool calling with reasoning switched on. If your product uses tools and you want newer models, that settles it.
Chat Completions next to Responses
| In Chat Completions | In Responses |
|---|---|
| A messages array | An input, either a string or a list of input Items |
| System or developer guidance in the messages | Top-level instructions |
| The reply sits in choices, inside a message | A typed output array of Items, with an output_text helper |
| A tool or function call | A function_call output Item |
| The tool result | A function_call_output input Item, linked by call_id |
| Several drafts at once with the n parameter | Not available; make separate requests |
| Structured Outputs set with response_format | Set with text.format |
The plain version of that table: Chat Completions glued everything about a turn into one message. Responses splits it into separate Items, so a message, a piece of reasoning, a function call and its result are each their own thing. That's tidier, but it means any code that assumed "everything is a message" needs changing. And if your tool asked the model for three draft headlines in one call, it now needs three calls.
Storage, privacy and Zero Data Retention
This is the section to read if you handle client data. Responses are stored by default. Chat completions are stored by default for new accounts too. In either API, setting store to false turns storage off.
Some organisations have Zero Data Retention requirements and can't use Responses in its stateful mode at all. For them, OpenAI offers encrypted reasoning items: you set store to false and replay every reasoning item the API returns, each of which carries encrypted content. For ZDR organisations, OpenAI enforces store false automatically, decrypts that content in memory to produce the next answer, then discards it. The question to ask your developer is simple: which of our flows store data with OpenAI, and do we have a ZDR agreement?
The three settings worth asking your developer about
store: false
previous_response_id
text.format
The migration mistakes OpenAI lists
OpenAI's guide ends with a list of common migration errors. In plain words, the ones I'd flag to any team:
- Reading the reply from the old place, choices, instead of output_text or the output array.
- Treating every output entry as a message, when reasoning and tool calls are separate Item types.
- Dropping reasoning or function-call Items when carrying a conversation forward by hand.
- Sending a function result without the matching call_id.
- Keeping response_format instead of switching to text.format.
- Reusing old streaming code that doesn't understand the new typed events.
The last item on OpenAI's list is the one that hits the budget. Chaining turns with previous_response_id is convenient, but it doesn't make earlier context free. The guide says all previous input tokens in the chain are still billed as input tokens. It also says previous_response_id doesn't carry over the previous response's top-level instructions, so your instructions need sending every time.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
What happened to the Assistants API
The OpenAI Assistants API was officially sunset on August 26, 2026, and is no longer available. If a tool you rely on was built on it and still works, it's already moved. OpenAI's Assistants migration guide maps the old pieces to the new ones:
- Assistants become Prompts, which can only be created in the dashboard and can be versioned.
- Threads become Conversations, which hold Items, not only messages.
- Runs become Responses.
- Run steps become Items.
The practical steps it gives: identify each assistant's bundle of instructions and tools, recreate it in the dashboard as a named prompt, store the prompt ID in source control, and test changes by swapping prompt IDs. One handy detail: the same prompt can be reused with the Realtime API, so your voice and chat behaviour can come from one definition.
A one-flow-at-a-time rollout
- Start with a simple text-generation flow, not your most complex one.
- Update the endpoint, the request body and how the output is read.
- Decide how that flow keeps state: previous_response_id, replaying Items yourself, or the Conversations API.
- For stateless or ZDR flows, add store false and include encrypted reasoning items where reasoning needs to carry across turns.
- Move function definitions across and check every function result carries the right call_id.
- Move Structured Outputs schemas to text.format and update streaming code.
- Compare behaviour, speed, token usage and errors before sending more traffic to Responses.
My advice if your developer says it's time
I'd build anything new on Responses from today, and skip a big-bang migration of everything that already works. Chat Completions remains supported, so there's no fire. Move one flow at a time, starting with the one that would gain most from built-in tools or newer models, and keep an eye on token usage when you chain conversations. If you're weighing OpenAI against other providers while you're at it, here's my round-up of other model APIs, and if your company buys through Microsoft, the Microsoft route to the same models is worth a read.
If a developer has told you your AI tools need migrating and you'd like a plain-English second opinion, that's the kind of AI enablement I help with. I run AI training and workshops for teams, and help businesses with AI enablement and workflow automation, so the busywork runs itself and people get time back. Most of that work is with SaaS marketing teams and small businesses. Here's how we can work together.
Frequently asked questions
What is the OpenAI Responses API?
It's OpenAI's recommended API for new projects, an evolution of Chat Completions with built-in tools, an agentic loop that can call several tools in one request, and optional stored conversation state.
Is Chat Completions being shut down?
No. OpenAI's migration guide says Chat Completions remains supported, but Responses is recommended for all new projects.
What happened to the OpenAI Assistants API?
It was officially sunset on August 26, 2026, and is no longer available. Assistants map to Prompts, Threads to Conversations, Runs to Responses and Run steps to Items.
Does previous_response_id save on tokens?
No. OpenAI says all previous input tokens in the response chain are still billed as input tokens.
How do I stop OpenAI storing my responses?
Set store to false. Organisations with Zero Data Retention can use encrypted reasoning items to keep reasoning working across turns without stored state.
