OpenAI deprecated the Assistants API on August 26, 2025, with a one-year shutdown window. On August 26, 2026, the /v1/assistants and /v1/threads endpoints will stop accepting requests permanently. If your application uses Assistants, Threads, Runs, or Messages through these endpoints, you need to migrate to the Responses API before that date.
The Responses API is not a rename. It is an architecturally different approach to building AI-powered applications. Understanding the conceptual differences is critical to a successful migration.
What is being deprecated
The following resources and endpoints are shutting down:
- Assistants (
/v1/assistants) - Persistent AI agent configurations stored on OpenAI’s servers - Threads (
/v1/threads) - Conversation state managed by OpenAI - Runs (
/v1/threads/{thread_id}/runs) - Execution instances of an assistant against a thread - Messages (
/v1/threads/{thread_id}/messages) - Individual messages within a thread
Every feature built on these primitives needs to be redesigned. This includes file search (formerly retrieval), code interpreter sessions tied to threads, and function calling workflows that depend on the run lifecycle.
OpenAI achieved feature parity in the Responses API before announcing the deprecation, meaning every capability available in the Assistants API has an equivalent path in the new system.
Timeline
- August 26, 2025 - Deprecation announced. Assistants API marked as legacy in documentation.
- August 2025 to August 2026 - One-year migration window. Both APIs functional simultaneously.
- August 26, 2026 - Final shutdown. All Assistants API endpoints return errors.
OpenAI gave a full year for migration, which is generous by API deprecation standards. However, the migration is not trivial for applications that rely heavily on OpenAI-managed state.
What replaces it
The Responses API replaces the Assistants API for single-turn and stateless interactions. For applications that need multi-turn conversation state, OpenAI also introduced the Conversations API as a complement.
The key architectural shift: the Assistants API was a stateful, server-managed system. OpenAI stored your assistant configurations, maintained conversation threads, and managed execution state. The Responses API is stateless. You send a request, you get a response. State management is your responsibility.
This is a philosophical change in how OpenAI wants developers to build applications. Rather than delegating state to OpenAI, you own your conversation history, tool configurations, and execution flow.
Conceptual differences
Understanding these differences is essential before writing any migration code.
Assistants API (old model)
- Stateful objects on OpenAI’s servers. You create an assistant once, and it persists with its instructions, tools, and model configuration.
- Threads as persistent state. Conversations live on OpenAI’s infrastructure. You append messages to a thread, and OpenAI maintains the full context.
- Runs as execution. To get a response, you create a run against a thread. The run manages tool calls, retries, and multi-step reasoning.
- Server-side orchestration. OpenAI handles the loop of calling tools, appending results, and continuing generation.
Responses API (new model)
- Stateless single calls. Each request contains everything needed: the model, instructions, tools, and conversation history.
- You manage state. Want multi-turn conversations? You store the messages and send the full history (or a summary) with each request.
- Tools attach per-request. Instead of configuring tools on an assistant object, you specify available tools in each API call.
- Client-side orchestration. You handle the tool-call loop: receive a tool call, execute it, send the result back in a follow-up request.
What this means in practice
If your application used the Assistants API as a convenience layer to avoid managing conversation state, you now need to build that state management yourself. This could mean:
- Storing conversation histories in your own database
- Implementing context window management (truncation, summarization)
- Building the tool-call execution loop in your application code
- Managing concurrent conversations without relying on OpenAI’s thread isolation
Migration planning
What changes
No more assistant objects. You cannot pre-configure an assistant with a system prompt, tools, and model, then reference it by ID. Instead, include your system prompt, tool definitions, and model choice in every request.
No threads as persistent state. If you relied on threads to maintain conversation context, you need to store messages yourself and pass relevant history with each API call.
Tools attach per-request, not per-assistant. Function definitions, file search configuration, and code interpreter access must be specified in each request body.
No run lifecycle. The concept of creating a run, polling for status, and handling requires_action states is gone. The Responses API returns results directly (or streams them). Tool calls come back in the response, and you send tool results in a follow-up request.
What stays similar
- The same underlying models are available
- Function calling works conceptually the same way (define functions, receive calls, return results)
- File search and code interpreter capabilities exist in the new API
- Streaming is supported
Migration approach
- Inventory your Assistants API usage. List every assistant you have created, what tools each uses, and how threads are managed in your application.
- Map each assistant to a request template. Convert each assistant’s system prompt, model, and tools into a request payload that you will send with the Responses API.
- Build state management. If you use threads, implement conversation storage. This could be as simple as an array in memory for short-lived chats, or a database for persistent conversations.
- Implement the tool-call loop. If your assistants use function calling, build the client-side loop: send request, check for tool calls, execute tools, send results, repeat until the model returns a final response.
- Test thoroughly. The behavior of stateless requests may differ subtly from assistant-managed runs, especially for complex multi-step tool usage.
Common mistakes
Treating it as a drop-in replacement
The Responses API is not a renamed Assistants API. Developers who try to find one-to-one mappings for every Assistants API concept will struggle. The mental model is different: you are moving from “OpenAI manages my AI agent” to “I build my AI agent using OpenAI as the inference layer.”
Keeping deprecated terminology in code
If your codebase has abstractions named createAssistant, addToThread, or startRun, rename them during migration. Keeping old terminology creates confusion when onboarding new developers or debugging issues against current documentation.
Ignoring that conversations need the Conversations API
The Responses API alone does not provide multi-turn conversation management. If your application has persistent conversations, you either need to:
- Manage state yourself (store messages, send history with each request)
- Use the Conversations API that OpenAI provides alongside the Responses API
Do not assume the Responses API handles conversation continuity. It does not.
Not accounting for increased latency in tool-call loops
With the Assistants API, OpenAI ran the tool-call loop server-side. With the Responses API, each tool-call round trip goes through your infrastructure. For assistants that make multiple sequential tool calls, this adds network latency at each step.
Underestimating the testing burden
Stateless requests can produce different results than stateful runs, especially when context window management differs. Budget time for regression testing, particularly for complex workflows with multiple tool calls or long conversation histories.
Frequently Asked Questions
Will my existing assistants and threads be deleted on August 26?
Yes. After shutdown, you will no longer be able to access assistant configurations, thread histories, or run logs through the API. Export any data you need before the deadline.
Can I still use the OpenAI Python/Node SDK?
Yes. The official SDKs support the Responses API. Update to the latest SDK version to access the new endpoints and helpers. The SDK documentation includes migration examples.
What if my application only makes simple single-turn calls?
If you only ever created a thread, added one message, and ran it once, your migration is straightforward. Replace the multi-step thread+run flow with a single Responses API call that includes your message and system prompt.
Does the Responses API support streaming?
Yes. Streaming is supported and works similarly to other OpenAI streaming endpoints. You receive server-sent events as the model generates its response.
What about file search and code interpreter?
Both capabilities are available in the Responses API. The configuration is per-request rather than per-assistant, but the underlying functionality is preserved. Consult OpenAI’s migration guide for the exact parameter changes.
Sources
- Assistants API documentation (deprecation notice) - Official OpenAI deprecation announcement
- OpenAI platform migration guide - Step-by-step migration instructions
- Best AI API providers in 2026 - Alternatives to consider
- OpenRouter complete guide - Multi-provider routing that works with the Responses API
- AI API pricing compared - Cost comparison across providers
Last updated: August 7, 2026. The Assistants API shutdown is final. If you are considering this migration as an opportunity to evaluate other providers, see our guide to AI API providers and OpenRouter guide for multi-provider architectures.