What is the Responses API, and should you move from Chat Completions?

An API (application programming interface) is how a program, rather than a person in a chat window, talks to a model. OpenAI's most widely adopted endpoint so far is Chat Completions: you send a list of messages, each with a role such as "system" or "user," and get one reply back. On March 11, OpenAI added the Responses API, which it presents as Chat Completions' easy style joined to the tool features of its older Assistants API.

The question many builders are asking this month is practical: do I have to rewrite my code? No. OpenAI has said it remains committed to Chat Completions and will keep adding new models there when they don't depend on built-in tools. It recommends the Responses API for new projects, and its Python library's README now presents it as the primary way to call the models.

What actually changes

Three differences matter for everyday code.

The third row is the biggest change. Responses are stateful: OpenAI keeps each response, so a later call can point to an earlier one by its id. The cookbook example also shows you can branch from any earlier response, which is handy when a user wants to try a different direction.

A worked migration

Here is a small script that drafts a reply to a customer email and then shortens it. This is the Chat Completions version, written with the openai Python library (version 1.x).

from openai import OpenAI
client = OpenAI()   # reads OPENAI_API_KEY from the environment

email = "Hi, my order #1042 arrived with a cracked lid. Can you help?"
messages = [
    {"role": "developer", "content": "You write warm, brief customer-service replies."},
    {"role": "user", "content": f"Draft a reply to this email:\n{email}"},
]
first = client.chat.completions.create(model="gpt-4o", messages=messages)
draft = first.choices[0].message.content

messages.append({"role": "assistant", "content": draft})
messages.append({"role": "user", "content": "Shorten it to three sentences."})
second = client.chat.completions.create(model="gpt-4o", messages=messages)
print(second.choices[0].message.content)

And the same job with the Responses API. Upgrade the library first (pip install --upgrade openai), since support arrived in the March 11 release.

from openai import OpenAI
client = OpenAI()

email = "Hi, my order #1042 arrived with a cracked lid. Can you help?"
first = client.responses.create(
    model="gpt-4o",
    instructions="You write warm, brief customer-service replies.",
    input=f"Draft a reply to this email:\n{email}",
)
print(first.output_text)

second = client.responses.create(
    model="gpt-4o",
    instructions="You write warm, brief customer-service replies.",
    input="Shorten it to three sentences.",
    previous_response_id=first.id,
)
print(second.output_text)

The second call no longer rebuilds the message list; previous_response_id tells the API which conversation to continue. The system-style guidance moves into instructions. Everything else, including the model name and your API key, stays the same.

Should you switch?

A simple rule of thumb:

• Stay on Chat Completions if your app works, sends single questions or manages its own history, and needs no built-in tools. Also stay if you use other providers that copy the Chat Completions format, since your code then works across services.
• Move to Responses for new projects, for multi-turn assistants where resending history is a chore, or when you want web search or file search without building them yourself.
• Plan a move if you use the Assistants API. OpenAI intends to deprecate it once Responses offers the same features, with a target shutdown around mid-2026.

One caution for privacy-minded projects: stateful conversations mean the content is stored on OpenAI's servers. OpenAI says it does not train on business data by default, but check that storage fits your own rules before you send customer emails through it.

What do built-in tools like web search add?

With Chat Completions, a tool is something you build: you describe a function, the model asks for it, your code runs it and sends the result back. That is function calling, and it still works in both APIs. Built-in tools are different: OpenAI runs them. You list them in the request and the model decides whether to use them, all in one call.

Adding web search to the second script takes one line: tools=[{"type": "web_search_preview"}] in client.responses.create. The model can then look up current information and return an answer with cited sources, using the same search models behind ChatGPT search. OpenAI lists web search at $30 per thousand queries with GPT-4o and $25 with GPT-4o mini, on top of normal token costs, so test with a few queries first.

The other built-in tools follow the same pattern. File search looks through documents you have uploaded to a vector store (a database that finds passages by meaning), and computer use, a research preview for some accounts, lets a model operate a browser or desktop. The benefit is fewer moving parts in your code; the trade-off is less control over exactly how the search is done, so keep checking the sources the model cites.