OpenAI Assistants API Shutdown: August 26 Migration Checklist

Direct answer: OpenAI’s Assistants API is scheduled to shut down on August 26, 2026. The official replacement is the Responses API plus Conversations API. If your code still calls openai.beta.assistants, openai.beta.threads, or thread runs, inventory and migrate those paths now.[1][2]

Deadline alert: Do not treat this as a model-name update. OpenAI changed the object model: Assistants become configuration passed to Responses (or stored prompts where appropriate), Threads become Conversations, Runs become Responses, and Run Steps become Items.[1]

What to do first

Use this order to reduce migration risk:

1. Search every service, automation, worker, and no-code connector for Assistants API calls.
2. Record each assistant’s instructions, model, tools, files/vector stores, metadata, and production owner.
3. Move new chats to Responses and Conversations first.
4. Backfill only the historical threads that users still need.
5. Rebuild and test tool-call loops, streaming consumers, retrieval, retries, and error handling.
6. Run the old and new implementations in parallel on a fixed evaluation set.
7. Cut over gradually, monitor errors and cost, then remove legacy credentials and code.

OpenAI says it will not provide an automated Threads-to-Conversations migration tool; its guidance is to start new chats on Conversations and migrate older threads as necessary.[1]

Assistants API to Responses API mapping

Assistants API	Replacement	Practical meaning
Assistant	Direct model/instructions/tools configuration or a managed prompt	Move behavior and tool definitions out of the Assistant object.
Thread	Conversation	Store messages, tool calls, tool outputs, and other items.
Run	Response	Send input and receive output items without polling a Run in the basic case.
Run Step	Item	Handle messages and tool activity as generalized items.

This mapping is documented in OpenAI’s official migration guide.[1]

Quick code migration: Python

Before: Assistants API

import time
from openai import OpenAI

client = OpenAI()

thread = client.beta.threads.create()
client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Summarize the deployment risks."
)

run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id="asst_..."
)

while run.status in ("queued", "in_progress"):
    time.sleep(1)
    run = client.beta.threads.runs.retrieve(
        thread_id=thread.id,
        run_id=run.id
    )

After: Responses API with a Conversation

from openai import OpenAI

client = OpenAI()

conversation = client.conversations.create(
    metadata={"user_id": "customer_123"}
)

response = client.responses.create(
    model="YOUR_SUPPORTED_MODEL",
    instructions=(
        "You are a deployment reviewer. Return risks by severity, "
        "then list verification steps."
    ),
    input=[{
        "role": "user",
        "content": "Summarize the deployment risks."
    }],
    conversation=conversation.id,
)

print(response.output_text)

The official guide shows this simpler Responses pattern and the use of a Conversation ID for persistent state.[1]

Keep the model name in configuration rather than hard-coding it across the application. Select a model that is currently available to your project and verify its behavior with your own evaluations.

Minimal stateless migration

If you do not need server-side conversation persistence, begin with a direct Responses call:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="YOUR_SUPPORTED_MODEL",
    instructions="Answer concisely and identify uncertainty.",
    input="Explain the rollback plan for this release."
)

print(response.output_text)

For a short multi-turn chain, OpenAI also documents previous_response_id. For long-lived state shared across sessions, use a Conversation and save its ID against your own user or session record.[3]

Find Assistants API usage before it breaks

Run searches across application code, infrastructure repositories, serverless functions, and automation exports:

rg -n "beta\.assistants|beta\.threads|assistant_id|thread_id|runs\.create" .

Also inspect:

• background workers and scheduled jobs
• webhook handlers
• support bots and internal knowledge assistants
• Make, Zapier, n8n, Bubble, or custom low-code connectors
• environment variables such as OPENAI_ASSISTANT_ID
• stored thread IDs in databases
• dashboards or admin tools that create assistants dynamically

A clean code search is not enough if an external automation platform still calls the retired endpoints.

Historical thread migration plan

OpenAI’s example migration reads messages from an existing Thread in ascending order, converts each message to a Conversation item, and creates a Conversation containing those items. There is no official automatic migration utility.[1]

Use this production-safe approach:

1. Identify active users and threads with recent activity.
2. Keep a mapping table: legacy_thread_id → conversation_id.
3. Export messages in chronological order.
4. Convert user text to input items and assistant text to output items.
5. Handle images, files, annotations, and unsupported content types explicitly.
6. Create the Conversation and store its ID.
7. Compare message counts and selected message hashes.
8. Run a read-only acceptance test before routing live traffic.
9. Retain the old mapping and export until the cutover is verified.

Do not silently discard tool results, file references, or assistant outputs just to make the import succeed.

Important prompt warning

OpenAI’s migration guide describes converting Assistants into dashboard-managed prompts, but the same current guide also warns that reusable prompt objects are being deprecated and tells developers to review the prompt deprecation timeline before using that path for a long-lived integration.[1]

That means you should not blindly replace one retiring persistent object with another. For a new implementation, first evaluate whether passing model, instructions, and tools directly to responses.create() is the cleaner option. If you do use a managed prompt during migration, pin or version it deliberately, document why it is used, and track the latest official deprecation guidance.

Tool and retrieval checklist

• [ ] Map each Assistant tool to its Responses equivalent.
• [ ] Re-test every function schema and required field.
• [ ] Execute function calls in your application and return tool outputs with the correct call ID.
• [ ] Confirm file-search/vector-store access with representative documents.
• [ ] Test Code Interpreter or other hosted tools separately.
• [ ] Verify streaming event names and your client-side parser.
• [ ] Add timeouts, retries, idempotency, and dead-letter handling.
• [ ] Log response IDs, conversation IDs, tool calls, latency, token usage, and failures.
• [ ] Redact secrets and personal data from logs.
• [ ] Test refusal, incomplete response, rate-limit, and tool-failure paths.

The Responses/Conversations model stores generalized items, including messages, tool calls, and tool outputs, rather than limiting a thread to messages.[1]

State, retention, and cost checks

OpenAI’s conversation-state documentation says Response objects are saved for 30 days by default unless store=false is used. It separately states that Conversation objects and their items are not subject to that 30-day TTL, and that prior input tokens in a previous_response_id chain are still billed as input tokens.[3]

Before rollout:

• decide whether each workflow should be stateless, chained, or Conversation-backed
• review data-retention requirements with the system owner
• test deletion and account-erasure workflows
• measure total input tokens across long conversations
• add summarization or compaction where appropriate
• compare old versus new cost per completed task, not only cost per request

Cutover test plan

Create 20–100 representative cases covering easy, difficult, and failure scenarios. Compare the legacy and replacement implementations on:

• answer correctness
• retrieval citations
• tool-call success rate
• structured-output validity
• latency at p50 and p95
• input and output tokens
• retries and rate-limit errors
• cost per successful task
• safety and data-handling requirements

Then route a small percentage of production traffic to the new path. Keep a configuration-level rollback switch until the migration has passed a full business cycle.

Rollback checklist

• [ ] Keep legacy and replacement paths behind a feature flag during testing.
• [ ] Store Conversation IDs separately from legacy Thread IDs.
• [ ] Avoid writes that only one path understands during the parallel-run window.
• [ ] Document the rollback owner and decision threshold.
• [ ] Alert on elevated API errors, tool failures, latency, or cost.
• [ ] Complete rollback testing before the August 26 shutdown; the retired API is not a rollback target after the deadline.[1][2]

FAQ

When does the OpenAI Assistants API shut down?

OpenAI lists August 26, 2026 as the Assistants API shutdown date.[1][2]

What replaces the Assistants API?

OpenAI recommends the Responses API and Conversations API. In the new object model, Runs become Responses and Threads become Conversations.[1][2]

Will OpenAI automatically migrate Threads to Conversations?

No. The official migration guide says OpenAI will not provide an automated tool for migrating Threads to Conversations. It recommends moving new chats first and migrating old threads as needed.[1]

Can I keep multi-turn conversation history?

Yes. You can attach Responses to a Conversation for durable server-side state, chain shorter interactions with previous_response_id, or manage history yourself.[1][3]

Do I have to create a stored prompt?

Not necessarily. Responses requests can carry model, instructions, tools, and input directly. OpenAI’s current migration page also warns that reusable prompt objects are being deprecated, so check the latest official guidance before designing around them.[1]

What should I test before cutover?

Test retrieval, files, function calls, hosted tools, streaming, structured outputs, conversation state, retention, latency, token usage, errors, and rollback. Use real evaluation cases rather than assuming object mapping guarantees equivalent behavior.

Bottom line

The deadline is close enough that production teams should begin with inventory and a parallel implementation now. Move new sessions to Responses and Conversations, migrate only the historical state that still matters, test every tool path, and complete rollback testing before August 26, 2026.[1][2]

Sources

[1] https://developers.openai.com/api/docs/assistants/migration — Assistants migration guide | OpenAI API
[2] https://developers.openai.com/api/docs/deprecations — Deprecations | OpenAI API
[3] https://developers.openai.com/api/docs/guides/conversation-state — Conversation state | OpenAI API