Source: Migrate to the Responses API (OpenAI guide)
OpenAI's migration guide from Chat Completions to the Responses API: items vs messages, instructions, storage defaults, state options, tool and schema format changes, and gotchas.
Contents
- What: official migration guide
- Publisher: OpenAI
- Date: living document; read 2026-11-14
- Original: Migrate to the Responses API
Summary
Explains how the Responses API differs from Chat Completions and what breaks when you port code. The central change is that input and output are lists of typed items rather than chat messages, and that the server can hold conversation state for you. It also records the Assistants API sunset.
Key claims
- Input and output are typed items (
message,reasoning,function_call,function_call_output), notmessages; text is read fromoutput_textor by walkingoutput. - No
n: Responses returns a single generation. - System guidance goes in a top-level
instructionsparameter. - Responses are stored by default;
store: falsedisables it. ZDR organizations havestore: falseenforced. Chat Completions are stored by default for new accounts (re-checked 2026-11-14). - Three ways to carry state:
previous_response_id, replaying output items manually, or a Conversations API object. - Function tool definitions are internally tagged (fields at top level) instead of nested under
function. - Responses tries strict mode when
strictis omitted and falls back if the schema is incompatible; Chat Completions defaults to non-strict. - Structured Outputs move from
response_formattotext.format. - Hosted tools (web search, file search, computer use, code interpreter, image generation, remote MCP) exist only in Responses.
- Streaming uses typed semantic events rather than
deltachunks. - The Assistants API was sunset on 2026-08-26.
- Gotchas: not every output item is a message; dropping reasoning or function-call items breaks continuity; results need the matching
call_id;previous_response_iddoes not carry overinstructionsand does not reduce cost (the whole chain is billed as input). - From GPT-5.4, Chat Completions supports tool calling only with
reasoning_effort: none; GPT-6 Astra and GPT-6.1 Sol need Responses for tool calling. - Stateless/ZDR: set
store: falseand replay every reasoning item, which carriesencrypted_content.