What the “Responses” API Name Actually Changed

A rename in an API is usually cosmetic. This one is not: the move from “chat completion” to “response” describes a different object coming back, and nearly every renamed field on the newer endpoint is downstream of that. This page explains the words. It does not rank the two endpoints and it contains no migration code — that is the rewrite page.

What the word was doing

“Completion” is inherited from the original text-completion interface: you sent a prefix, the model completed it. When chat arrived, the interface kept the noun — you sent a transcript, and what came back was the completion of that transcript, a single assistant message. The shape of the reply reflects that lineage exactly: choices, an array of alternative completions, each holding one message with a role and a content string. Plural only because you could ask for several alternatives of the same thing.

That model held while a turn produced one thing. It stopped holding when a turn started producing several things of different kinds: some visible text, some tool calls, and — with reasoning models — an internal reasoning segment that is billed, sometimes summarised, and not the same category of object as an assistant message. Fitting three kinds of output into one message means bolting fields onto it: the tool calls became an optional array on the message, the reasoning tokens became a count in a usage sub-object, and the message’s content could be null while the turn had plenty of content in it. That is the strain the rename is a response to.

Output items, not a completed message

The structural change is that the newer shape returns output, an ordered array of typed items, instead of choices. An item has a type. A message item holds content parts, where a text part is typed output_text. A function_call item is its own item, sitting beside the message rather than inside it, and carries a call_id along with the function name and its arguments as a JSON string. A reasoning item is likewise its own item.

So the promotion is the point: things that were fields on a message become siblings in a list. Once you see that, three consequences follow without being separately announced.

• Order is now expressed. A turn that reasons, calls a tool, then speaks is a three-element array in that order. In the older shape the ordering between a tool call and accompanying text was implicit.
• There is no single “the text”. Getting the assistant’s prose means walking the array for message items and concatenating their output_text parts. The official clients expose a convenience accessor — output_text on the response object — precisely because that walk is tedious and everyone writes it.
• New output kinds are additive. A new item type appears in the array and a consumer that switches on type ignores it. Under the old shape, a new output kind had to become a new field on the message, which is a change every consumer sees.

Endings stopped being one field

The older shape reports how a turn ended with finish_reason on each choice, taking values such as stop, length, tool_calls and content_filter — the library enumerates them in the finish reason values. That single field is doing two jobs: saying whether the request finished, and saying why the generation stopped.

The newer shape splits them. The response object carries a status — completed, incomplete, failed, or an in-progress state for asynchronous use — and where it is incomplete, a separate incomplete_details object says why, for example that the output token cap was reached. Anthropic makes a parallel distinction with a differently named field, stop_reason, on the message.

The practical difference for a caller is where the truncation check lives. Under the old shape, truncation is a value of the same field that reports normal completion, so a consumer that only handles stop silently treats a cut-off answer as a good one. Under the new shape, truncation changes the top-level status, so the same oversight fails visibly.

The renames that follow

Most of the field renames are the same idea reappearing: a name that described a chat transcript is replaced by one that describes an input and an output.

• messages becomes input, and it accepts a plain string as well as an array of items. The array is no longer only messages — a tool result is an input item too.
• The system message becomes a top-level instructions parameter, which is closer to how Anthropic’s Messages API has always treated system: a thing about the call rather than a turn in it.
• max_tokens becomes max_output_tokens. This one is a genuine clarification rather than a rename: the older name was routinely misread as a total budget, which is the confusion context window versus max tokens exists to settle.
• response_format becomes a format nested under a text object, because it configures the text output specifically rather than the response as a whole.
• Usage counts move from prompt_tokens and completion_tokens to input_tokens and output_tokens, with cached and reasoning counts in per-direction detail objects. This is the rename most likely to break something quietly, because cost dashboards read those keys by name and a missing key reads as zero rather than as an error.
• Two parameters have no older counterpart at all: store and previous_response_id. They exist because the endpoint can hold conversation state for you, which is a different subject — mapping conversation state when an API keeps it.

Why both shapes exist at once

Neither shape is a replacement in the sense of one switching off. The chat-completions shape has become an informal interoperability standard: a great many providers, proxies, local runtimes and frameworks accept it, so code written against it runs against far more endpoints than code written against any single vendor’s newer object model. That portability is a real property and it is independent of which design is tidier.

The newer shape buys the opposite trade: a richer object model, room for output kinds that did not exist when the old one was designed, and optional server-side state — at the cost of being one vendor’s shape rather than everybody’s. Which of those you want depends on whether you expect to call one provider or several, and that is a decision about your architecture rather than about the APIs. If you expect several, the thing to design is your own internal shape and the adapters onto it, which is the same conclusion writing provider-agnostic code reaches from the other direction.