OpenAI responses API reference

OpenAI's Responses API brings model responses, tools, and conversation state into one interface. If you're a developer building anything that feels like an AI agent, you're probably trying to figure out where it fits into your stack. Good news, you're in the right place.

This guide is a straightforward reference to help you understand what this new API is, how it stacks up against OpenAI's other tools, and where operating an existing support teammate through eesel CLI fits alongside building a custom application. Let's dig in.

What is the OpenAI Responses API?

The OpenAI Responses API is the company's newest and most advanced way to get responses from their models. Its main job is to make it easier to build stateful, multi-turn conversations where the AI can use tools and actually remember what you were just talking about.

Both APIs can support multi-turn applications. With Chat Completions, your application supplies the conversation history. Responses also offers server-managed state, alongside the option to pass context yourself.

This new API rolls a few key features into one place that used to require a lot of manual coding:

• It remembers the conversation: The API can natively keep track of a conversation's context, so you don't have to keep stuffing the entire chat history into every single request.

• It has built-in tools: It ships with powerful tools like web search and file search right out of the box, letting the model pull in information that goes way beyond its training data.

• It brings everything together: It simplifies building complex AI agents by combining features from both the Chat Completions and Assistants APIs into a single, more direct interface.

As some folks in the developer community have noted, this is a move toward a more integrated, all-in-one service. While that makes a lot of development tasks easier, it's also a shift away from the simple, interchangeable endpoints that many open-source tools were built to use.

Reddit

Key features of the OpenAI Responses API

The real magic of the Responses API is in its integrated features, which handle tasks that used to be a massive headache to manage yourself. It's no longer just about getting a chunk of text back; it's about building an agent that can remember, learn, and take action.

Stateful conversation management

One of the biggest improvements is that the API is now "stateful," which is just a fancy way of saying it can remember your conversation. You don't have to manually pass the entire chat history back and forth anymore. The Responses API gives you two main ways to do this.

1. "previous_response_id": This is the easy route. You just pass the ID of the last response, and the API automatically links the new turn to the old one. It's perfect for creating simple, linear conversations without much hassle.

2. "conversation" object: Use a persistent conversation to retain items across calls. Alternatively, pass context manually when your application needs to manage it itself. Choose the approach that fits your retention and application requirements.

Those state mechanisms belong to your OpenAI application. An eesel teammate has its own workspace and conversations, accessible through eesel CLI. If you use both services, keep their conversation identifiers and access rules separate rather than assuming one carries over to the other.

Built-in tools

"Tools" are what give an AI model its superpowers, letting it break out of its knowledge bubble and interact with the world. The Responses API comes with some impressive ones built right in.

• Web Search: The model can browse the web for current information and give you answers with sourced citations. This is huge for any use case that needs up-to-the-minute info.

• File Search: You can give the model your own files, and it can perform a semantic search over them. It's great for building a Q&A bot that knows your company’s internal knowledge base inside and out.

• Code Interpreter: This tool gives the model a safe, sandboxed Python environment where it can write and run code. It's incredibly useful for analyzing data, solving tough math problems, or even generating charts on the fly.

For file search, you supply uploaded files and a vector store. For an existing eesel teammate, CLI commands instead let you inspect connected sources, upload knowledge, and ask questions through that teammate. These are different ways to organize the work, not interchangeable API calls.

Structured outputs

The Responses API also makes it easier to get predictable, structured data back from the model. In Responses, configure a JSON schema through text.format, rather than the Chat Completions response_format parameter. This is perfect for things like automatically extracting a user's contact details from a support ticket or pulling product info from a customer question.

Responses API, Chat Completions, and the retired Assistants API

OpenAI recommends Responses for new projects, while Chat Completions remains supported. The Assistants API was retired on August 26, 2026.

When linking responses, do not assume everything carries forward. Resend stable top-level instructions on each request. Keep tool results associated with their call IDs, and do not treat every item in the output array as an assistant message. Those details matter when a workflow uses more than one tool.

Operate the support teammate through eesel CLI

If your Responses API research is aimed at customer support, I would first ask what needs to be custom. You may need a new application, or you may need a development-friendly way to work with a teammate that already has support knowledge and instructions.

eesel CLI provides the latter. A person can use it in a terminal, a script can repeat its commands, and a coding agent such as Claude Code, Cursor, or Codex can read its JSON results. The CLI operates the same eesel AI teammate and workspace as the dashboard, so support colleagues keep access to the setup.

Inspect state where it actually lives

For an existing eesel workspace, use Node.js 18.17 or newer:

npx @eesel/cli login
npx @eesel/cli agents

Choose the support teammate and replace <agent-id> with its ID:

npx @eesel/cli status --agent <agent-id>
npx @eesel/cli instructions --agent <agent-id>
npx @eesel/cli activity --agent <agent-id>

Status shows connections and whether their content has downloaded. Instructions show the teammate's standing rules, while activity lets you inspect its recent work. None of these commands changes an OpenAI response or conversation object.

This is useful when diagnosing a bad support answer. Is the needed source downloaded? Does the instruction match the policy? What did the teammate actually do? A coding agent can help gather that information and propose a correction before you authorize any changes.

Test one answer with the right context

If you need to supply a local policy, upload the real file:

npx @eesel/cli files upload ./returns-policy.pdf --agent <agent-id>

Confirm the upload succeeds, then ask a realistic question:

npx @eesel/cli chat "What should we tell a customer returning an item without its original packaging?" --agent <agent-id>

Compare the answer with the policy and the standing instructions. An upload adds knowledge; it does not itself rewrite those instructions. A successful CLI response is evidence that the command ran, not proof that the answer is correct.

Put automation around explicit responsibilities

CLI output is JSON, and errors include a hint and retryability information. Your script or coding agent can inspect those results to decide what to check next. Start with a bounded request such as "Inspect the sources and instructions, explain the gap, and propose changes without applying them."

The CLI also exposes automations for configured event, scheduled, and webhook work, and approvals for actions held for a person. For write commands, --dry-run previews the server request without sending it. It does not simulate a customer conversation.

If a custom Responses application needs to interact with eesel, implement and test that connection explicitly. An OpenAI API key does not authenticate to eesel, and eesel commands do not accept OpenAI response IDs as their conversation state.

Compare the work and the bill separately

For an OpenAI application, estimate model and tool usage using the API pricing documentation, plus hosting and maintenance. Retaining context can affect usage, so measure representative multi-turn workflows.

For eesel, npx @eesel/cli billing reports the workspace's current billing state. This is separate from any OpenAI API usage.

Choose between building a workflow and operating a teammate

Responses is a flexible foundation for an application that needs model outputs, tools, and conversation state. eesel CLI gives developers and coding agents access to a support teammate that the business can also manage in the dashboard.

If that is the support workflow you need, try eesel and follow the CLI guide. Inspect the sources and instructions, test a relevant policy question, and decide what custom application work remains.