Assistants API ends on August 26th: checklist to migrate without losing conversations and tools

OpenAI has scheduled the removal of the Assistants API for August 26, 2026 and indicates the Responses API, combined with the Conversations API, as a replacement. As of August 3, the date of this review, there are 23 days left to eliminate dependency on old endpoints.

The Assistants API migration should not be treated as a simple URL change. The old architecture distributes state and behavior among Assistants, Threads, Messages, Runs, Run Steps, files, and tool resources. In the current model, these responsibilities are transferred to configurations maintained by the application, Conversations, Responses and different types of items.

The biggest risk is not a call crashing. It's an integration to go back online without the correct history, call tools with different arguments, lose links to files, or be unable to explain what happened during a run.

What really changes on August 26th

The official documentation presents four conceptual equivalences:

• Assistants give rise to the behavior configuration used in requests;
• Threads are replaced by Conversations;
• Runs become Responses;
• Run Steps become different types of Items, including messages, tool calls, and results.

There is, however, an important update for projects that began migration following previous versions of the guide. The documentation still shows the transformation of Assistants into Prompt objects, but reusable prompts have also been discontinued: creation was deprioritized on June 3, 2026 and the closure of v1/prompts is scheduled for November 30, 2026. The most recent recommendation is to keep instructions and other prompt content in the code or configuration layer of the application itself.

So moving from Assistant to a reusable Prompt today might just trade an August deadline for a November deadline.

Matrix: old resource and current equivalent

The table is a starting point. Your application's actual contract may include behaviors that do not appear in OpenAI objects, such as permissions, per-client limits, deduplication, auditing, and confirmation before taking actions.

Take inventory before changing code

Assistants and settings

For each Assistant in use, record:

• ID and purpose;
• complete instructions;
• model and parameters;
• enabled tools;
• function schemas;
• associated files and vector stores;
• expected output formats;
• rules applied in the code before and after the call;
• environments, customers or products that depend on it.

Don't just copy the text from instructions. An Assistant can depend on resources in tool_resources, a structured schema, or logic applied during Run creation.

Transform this set into a versioned configuration in the repository. Each change must be reviewed, tested and possible to return to the previous version.

Threads, messages and users

Create a reconciliation table with at least:

The Threads API works with retrieving objects by thread_id. In practice, the database and application logs should be treated as the catalog of Threads that need to be migrated or archived.

The inventory must include all message pages, not just the first batch returned by the API. Also register:

• chronological order;
• role of the author;
• texts, images and files;
• attachments;
• notes and citations;
• metadata;
• relations with Runs;
• incomplete or error messages.

Persisted tools and resources

List separately:

• own functions and their schemas;
• external services called by functions;
• side effects such as shipping, purchasing or changing registration;
• uploaded files;
• vector stores and files contained in them;
• outputs produced by Code Interpreter;
• webhooks;
• streaming parsers;
• retention and deletion policies.

Inventory is completed only when each old resource has a destination, a documented disposal decision, or a backlog that blocks trimming.

How to preserve conversations

The Conversations API maintains a durable object that is reusable across sessions, devices, or tasks. A Conversation stores items, which can represent messages, tool calls, results, and other data.

OpenAI informs that there will not be an automatic tool to convert Threads into Conversations. The official guidance is to direct new chats to Conversations and migrate old ones as necessary. The guide also presents an example of a backfill that pages a Thread's messages in ascending order, converts the content into items, and creates a Conversation.

A safe strategy has four steps.

1. Stop creating new debt

Once the Responses path is validated, forward new conversations directly to the Conversations API. Immediately record the relationship between the session's internal identity and the new conversation_id.

2. Convert history on demand

When opening an old conversation:

1. find the thread_id;
2. recover all message pages;
3. convert accepted content types;
4. create the Conversation;
5. record the correspondence between the two IDs;
6. check count, order and content before releasing the response.

This process must be idempotent: two attempts to the same Thread cannot create two independent conversations.

The official backfill example covers text and image per URL. Integrations that use image_file, attachments, annotations, tool results, or proprietary formats need to extend the converter and test each type separately.

3. Keep a canonical copy

Do not depend on the future availability of old endpoints to reconstruct history. Before shutdown, preserve in your own storage the content necessary for continuity, auditing and recovery, in accordance with your legal basis and retention policy.

This copy must record the source and version of the converter. It doesn't need to reproduce every internal detail of OpenAI, but it should be enough to reconstruct the user experience.

4. Review retention and privacy

Stored responses have, by default, application state retention for 30 days. Conversations and their items remain until deleted and are not eligible for Zero Data Retention. A Response associated with a Conversation has its items preserved without the standard 30-day limit.

The choice between Conversations, threading by previous_response_id, or self-managed history must consider privacy, deletion, data residency, auditing, and contractual requirements — not just technical convenience.

How to migrate tools

Function calling

In the old model, a Run could enter requires_action. In the Responses API, the output contains function_call items. The application identifies each call, executes the corresponding function and returns a function_call_output item with the same call_id. The tool loop becomes the explicit responsibility of the application.

Tests must verify:

• function name;
• validity of arguments;
• missing or unexpected fields;
• parallel calls;
• timeout;
• repetition of the same action;
• error handling;
• confirmation for irreversible operations.

The documentation recommends schemas in strict mode. In this mode, objects must declare additionalProperties: false and mark defined fields as mandatory, using null when a value can be optional.

File Search

Vector stores continue to be used by file_search in both the Assistants API and the Responses API. Instead of depending on the link maintained in the Assistant or Thread, the new request informs the vector_store_ids in the tool configuration.

Before cutting, test:

• access to the same vector store;
• quantity and status of files;
• quality of responses;
• presence of citations;
• filters by metadata;
• permissions per user;
• behavior when no results are found.

Full search results are not included by default. For observability and debugging, the Responses API allows you to request file_search_call.results via the include parameter.

Code Interpreter

In the Responses API, the Code Interpreter uses a container. It can be created automatically or explicitly, with the necessary files. Containers should be treated as ephemeral resources: the documentation states that they expire after 20 minutes of non-use and that their data cannot be recovered after expiration.

Never use the container as definitive storage. Files produced that need to remain available must be copied to the application system while the container is active.

Long processes, polling and streaming

Short tasks can use synchronous Responses. For long executions, background mode allows you to track states such as queued and in_progress, retrieve the Response and cancel it. Webhooks can report events like response.completed.

Streaming has also changed. The Responses API emits semantic typed events, including creation, text deltas, tool calls, completion, and error. Parsers based on old events need specific testing; It's not enough to change the endpoint.

Regression testing matrix

Don't just compare literal sentences. Generative models can produce different texts and still fulfill the same contract. Evaluate facts, format, decisions, tool calls, security, and end effect.

Gradual cut and reversal plane

Place the new path behind a feature flag per client, user or session. Start with internal traffic, move up to a small group, and scale up only when metrics remain within defined limits.

During the cohabitation period:

• do not record the same external action twice;
• maintain correlation between old and new objects;
• compare failures, latency, tokens and tool calls;
• monitor conversations without mapping;
• block the deletion of legacy resources;
• preserve the ability to quickly deactivate the new path.

Before August 26th, rolling back may temporarily mean redirecting traffic to the legacy integration. After closure, this ceases to be a valid strategy. The post-deadline plan needs to fall back to a previous, stable version of the implementation in Responses, using the canonical state stored by the application.

Suggested schedule for the remaining 23 days

• August 3-6: Inventory, export and freeze of new legacy resources.
• August 7th to 13th: implementation of Conversations, Responses and tool adapters.
• August 14 to 19: controlled backfill, regression testing and parallel execution without effects.
• August 20 to 23: progressive cut and correction of divergences.
• August 24th and 25th: full operation on the new path, with on-call and rollback between Responses versions.
• August 26: no production journey should depend on Assistants, Threads, Messages, Runs or Run Steps.

This timeline is an editorial recommendation, not an official OpenAI calendar. Teams with high volume, regulatory requirements, or tools that produce external effects must anticipate steps and require formal technical approval.

Final Assistants API Migration Checklist

• All Assistants in production have been identified.

• Instructions, models, tools and schemas are versioned in the application.

• The final architecture does not rely on reusable prompts.

• All known thread_ids are linked to authorized users or sessions.

• The required history has been exported or converted.

• New sessions already create Conversations.

• The backfill is paged, idempotent, and auditable.

• Text, images, attachments and notes have been tested.

• Functions validate arguments and avoid duplicate effects.

• Vector stores and files have been reconciled.

• File Search results retain citations and permissions.

• Code Interpreter files are preserved outside the container.

• Polling, cancellation, webhooks and streaming have been updated.

• Retention, deletion and Zero Data Retention have been re-evaluated.

• There are comparable metrics between the old and new path.

• The cut is protected by a feature flag.

• There is rollback to a stable version based on Responses.

• No production streams will rely on the Assistants API on August 26.

The migration ends when the system can continue a conversation, retrieve the correct resources, run tools safely, and explain each step without referring to the legacy API. Changing the endpoint is just the beginning.

Updated August 3, 2026. Documentation, SDKs, and platform features may change before publishing or hard cutting.