Responses API vs Chat Completions: choose by contract, not novelty

Use Responses when its item-based output, tool loop, and state model solve a real requirement; keep Chat Completions when its message contract already meets the need and migration has no measured benefit.

Published 2026-08-15 · Updated 2026-08-15 · KeepRouter Editorial · 9 minute read

Protocol decision matrix for Responses API and Chat Completions integrations — Choose the contract your application consumes; similar prompts do not make response state or events interchangeable.

Short answer: Responses is a different application contract, not a renamed Chat Completions call. OpenAI describes Chat Completions as message input with choices containing messages, while Responses accepts flexible input and returns typed output Items. Choose Responses when its item model, built-in tools, or state handling solves a requirement. Keep Chat Completions when a message-in/message-out integration already meets the requirement and the migration work has no measured payoff.

Contract differences that affect code

Concern	Chat Completions	Responses	Migration question
Primary input	Message array	String or typed input Items	Can your prompt builder emit the new input form?
Primary output	Choices containing messages	Typed output Items; SDKs may expose an output-text helper	Does your parser preserve non-text Items?
Tools	Function/tool-call fields in the chat shape	Function calls and built-in tools represented as Items	Can your loop process every emitted item type?
Conversation state	Commonly carried by resending messages	Can chain responses or use conversation state	Who owns retention, deletion, and replay?
Streaming	Chat completion chunk events	Typed response lifecycle and item events	Is your UI/event consumer endpoint-aware?
Multiple generations	Supports the chat-specific choice pattern	The Responses migration guide documents a single generation	Does any caller rely on multiple choices?
Structured output	Chat-specific response format	A different text-format shape	Have schemas and refusal handling been retested?

OpenAI's migration guide says to treat migration as three changes: send to the Responses endpoint, read the typed output array, and decide how state moves between turns. That is a useful minimum. Production code should also test tools, streaming, storage settings, error mapping, usage accounting, cancellation, and any SDK helper that hides the raw response.

Choose with three questions

Do you need a Responses-only workflow? Built-in tools, an item-based agent loop, or response chaining may justify the new contract. Verify the exact model and account support rather than assuming every capability is universal.
What does the application currently consume? If the code only reads one text message, migration may be small. If it depends on choices, tool-call deltas, custom stream assembly, or stored chat history, enumerate each dependency.
Who owns state and data policy? Server-managed continuation can reduce payload plumbing, but it changes retention and deletion responsibilities. Read current data-control documentation and set storage behavior explicitly where supported.

A safe migration slice

[ ] Freeze a representative set of chat requests and expected structural assertions.
[ ] Create a separate Responses adapter; do not make one parser guess both event families.
[ ] Assert typed output Items, not only the SDK's aggregated text helper.
[ ] Exercise every tool definition and tool-result round trip.
[ ] Test storage disabled and enabled according to your data policy.
[ ] Compare usage records and request identifiers across the two paths.
[ ] Canary one bounded workflow, with a route-level rollback switch.

With KeepRouter, use the public OpenAPI document to verify whether the Responses route is present, and the model catalog to confirm the selected model's endpoint compatibility. Route availability and model eligibility are separate facts. The OpenAI-compatible API page gives the broader integration context, and the migration checklist covers SDK, errors, and rollout evidence.

Boundary: upstream guidance does not prove gateway parity

OpenAI's documentation is authoritative for OpenAI's endpoints. An OpenAI-compatible gateway may implement Chat Completions, Responses, both, or a subset of fields and models. A successful Chat Completions request is not evidence for Responses support. Check the gateway's current OpenAPI and model-level compatibility, then run a scoped request using the exact fields your application needs.

Frequently asked questions

Is the Responses API a drop-in replacement for Chat Completions?

No. Endpoint, input, output, tools, streaming events, and state handling differ. A thin adapter may be enough for simple text, but production migration still needs contract tests.

Does a gateway that supports Chat Completions also support Responses?

No. Verify the route in the current OpenAPI document and verify the selected model's endpoint eligibility separately.

Sources reviewed

Article last reviewed 2026-08-15