Migration verdict: treat this as a state-model migration, not an endpoint rename. OpenAI officially sunset the Assistants API on August 26, 2026, and says it is no longer available. The supported destination is the Responses API plus the Conversations API. New conversations should move first; old Threads should be backfilled only when they are still needed.
October 29 update: remove managed Prompt dependencies before November 30
Teams using OpenAI reusable Prompt objects or v1/prompts need to move that dependency before November 30, 2026, the scheduled shutdown date in OpenAI’s deprecations notice. The notice does not specify an exact cutover time or time zone. Plan to finish before November 30. This affects managed Prompt objects, not the use of prompts generally. See the official migration guide and our reusable prompts tracker record (932431).
Inventory each deployed Prompt ID and version across applications, jobs, environment settings and stored configurations. Preserve the actual versioned prompt content, variables, model and settings, tool definitions and any output requirements in application-owned version control. A prompt object can hold more than a text string; copying only its text can change the application’s behavior.
The following is an illustrative local application configuration, not an OpenAI request. It shows the dependency moving from a managed reference to an application-owned bundle. Fill the bundle with the actual values from your own version; these placeholders do not reproduce a real prompt.
Before:
{"managed_prompt": {"id": "example_prompt", "version": "1"}}
After:
{"prompt_bundle": {"version": "1", "content": "Example instructions with {{topic}}", "variables": ["topic"], "model": "YOUR_MODEL", "settings": {}, "tools": []}}
Have your application render variables and pass the resulting instructions and inputs to Responses using the current SDK contract. Preserve conversation state separately. Record a bundle version with each deployment so you can identify which instructions, tools and settings produced a response. Review how your application handles missing variables and tool permissions before enabling the new path.
In staging, compare representative conversations, tool calls, structured outputs, failures and state handling against your saved acceptance cases. Inspect the resulting traces and authorization boundaries. A feature flag and a small canary can limit the rollout while you investigate differences. Before shutdown, the old path may be a temporary fallback only while it remains available; after shutdown it cannot restore service. Roll back to a validated application-owned bundle or queue or disable the affected function.
This section reflects documentation reviewed October 29; the earlier Assistants and Threads discussion remains dated history. We locally parsed the illustrative JSON but did not test provider runtime behavior. The tracked documentation was conditionally revalidated at 19:30:07 and 21:35:06 UTC on October 29 with the same retained source hash; those observations do not establish when OpenAI edited the page.
For the wider decision path, continue through Kingy’s Model Economics and Migrations hub to connect this migration with pricing evidence, provider comparisons and canonical API records.
Source audit: checked against current OpenAI documentation on August 27, 2026. Track the underlying deadline on the AI Stack Change Radar and its Assistants API change record.
What broke on August 26
Requests to the Assistants API are no longer a viable production path. Applications that create or retrieve Assistants, Threads, Messages, Runs or Run Steps through the beta Assistants surface need a replacement. The important object mapping is:
| Assistants API | Replacement | Migration consequence |
|---|---|---|
| Assistant | Application configuration; existing Prompt objects only during transition | Move model, instructions and tool configuration into your code/configuration layer. Reusable Prompt objects are deprecated and scheduled to shut down on November 30, 2026. |
| Thread | Conversation | Store a new Conversation ID beside your own user/session key. |
| Message | Input/output item | Expect conversations to contain tool calls and tool outputs as well as messages. |
| Run | Response | Replace run polling and status handling with Responses API handling, streaming or background-mode logic as appropriate. |
| Run Step | Response item | Update tracing, audit logs and tool-call parsers to consume typed response items. |
Do not assume that preserving the same prompt text preserves the same behavior. State representation, tool-call events, retry logic, streaming events and observability all change.
Who is affected
- Applications that reference
client.beta.assistantsorclient.beta.threads. - Backends that persist
assistant_id,thread_id,run_idor Run Step IDs. - Tool integrations that submit outputs to an active Run.
- Support, compliance or analytics systems that reconstruct a session from Thread Messages.
- Queues that poll Run status or assume one active Run per Thread.
If your application already calls client.responses.create() and either passes a Conversation ID or manages state explicitly, this deadline may not affect that path.
Prerequisites
- Inventory every Assistants call. Search code, workers, notebooks and scheduled jobs for Assistants, Threads, Runs and Run Steps.
- Record the current contract. Save representative prompts, tool schemas, expected outputs, latency, token use, error rates and safety behavior.
- Separate configuration from state. Keep model, instructions and tools in versioned application configuration for the long term. If you still depend on a reusable OpenAI Prompt object, plan to remove that dependency before its scheduled November 30, 2026 shutdown.
- Add dual identifiers. Your data model needs room for both the legacy
thread_idand a newconversation_idduring rollout. - Pin a current OpenAI SDK. Upgrade in a branch and verify the Conversations and Responses methods used by your language SDK.
Exact migration steps
1. Freeze the legacy baseline
Capture at least 50 representative sessions, including tool success, tool failure, long conversations, file retrieval, malformed tool output, timeout and moderation cases. Store expected assertions rather than only screenshots.
2. Replace the Assistant with a versioned configuration
Move the Assistant’s model, instructions and tools into source-controlled application configuration. OpenAI’s documentation checked on October 8, 2026 says reusable Prompt objects and the v1/prompts API are also deprecated and scheduled to shut down on November 30, 2026. Treat any existing Prompt ID and version as a transitional dependency, not a permanent replacement. Preserve an existing read-only export of the legacy Assistant configuration for audit and reconstruction.
3. Create a Conversation for each new session
The example below assumes your application still has an accessible reusable Prompt. It illustrates that transitional configuration path; replace the Prompt dependency with application-owned configuration before its scheduled November 30 shutdown.
from openai import OpenAI
import os
client = OpenAI()
conversation = client.conversations.create(
metadata={"app_session_id": "session_123"}
)
response = client.responses.create(
prompt={"id": os.environ["OPENAI_PROMPT_ID"]},
conversation=conversation.id,
input=[{
"role": "user",
"content": "Summarize the customer issue and propose the next action."
}],
)
print(response.output_text)
Persist conversation.id against your own session key. A Conversation can store messages, tool calls, tool outputs and other items, so downstream readers must not assume every item is a user or assistant message.
4. Rebuild tool execution around response items
Keep tool schemas strict and versioned. When a response asks for a function call, validate its name and arguments, run the tool with least privilege, submit the tool output using the current Responses API pattern, and continue until a terminal response is reached. Add idempotency at your tool boundary so a retry cannot repeat a payment, ticket update or destructive write.
5. Change state lookup
Replace “load Thread, append Message, create Run” with “load Conversation ID, create Response with new input.” Keep the application session key as the durable lookup key; OpenAI object IDs should be replaceable implementation details.
6. Move new traffic before old history
OpenAI’s documented migration uses messages already stored by your application. The retired Assistants API call for retrieving Thread messages no longer works. Route new chats to Conversations immediately, and backfill legacy history only when a user resumes it or retention requirements justify the work. Read the saved messages in chronological order, transform supported text/image parts into Conversation items, create the Conversation, and record a one-time mapping from the legacy Thread ID to the Conversation ID. If you did not retain the history, do not assume it can now be recovered through the retired API.
7. Update observability
Log response IDs, conversation IDs, prompt version, model, tool-call IDs, finish state, latency, input/output tokens and error class. Do not carry Run Step dashboards forward unchanged; rebase them on response items and tool events.
Code and configuration checklist
- Remove new writes to
client.beta.assistantsandclient.beta.threads. - Version the application-owned instructions, model and tool configuration. Use
OPENAI_PROMPT_IDonly for an existing transitional Prompt dependency, and remove that dependency before its scheduled November 30 shutdown. - Add
conversation_idbeside—not over—thread_iduntil rollback closes. - Replace Run polling with Responses streaming, background processing or direct response handling appropriate to the workload.
- Update event parsers and audit schemas for response items.
- Make every state write and tool side effect idempotent.
Tests that must pass
- Golden behavior: required facts, refusal behavior and tool selection match approved expectations.
- Conversation continuity: a five-turn session preserves relevant facts without duplicating tool output.
- Tool contract: valid calls succeed; invalid arguments fail closed; repeated calls do not repeat side effects.
- Ordering: concurrent user messages and tool results do not corrupt state.
- Failure recovery: timeouts, 429s and 5xx responses use bounded retries and remain observable.
- Cost and latency: p50/p95 latency and token cost stay inside explicit release thresholds.
- Backfill: resumed Threads preserve the required user-visible history after selective conversion.
- Data controls: retention, deletion, access and regional-processing requirements remain satisfied.
Staged rollout
- Fixture shadow: replay captured sessions against Responses in a non-production environment.
- Staff canary: route employee traffic and synthetic monitors to the new Responses implementation.
- One percent: enable the new Responses build for a small cohort of sessions.
- Ten to fifty percent: expand by tenant while watching tool errors, latency, cost and safety metrics.
- Full cutover: promote the validated Responses path and retain the last-known-good Responses build.
- Selective history conversion: convert only the legacy history that users or retention requirements still need.
Rollback
The provider-level rollback to Assistants is closed. Use a server-side flag between the current and last-known-good Responses implementation, preserve the previous prompt/configuration version, keep Conversation mappings and migration ledgers immutable, and make schema changes backward compatible. If a release threshold fails, stop the rollout and restore the last validated Responses build and configuration.
Do not attempt to recover by calling Assistants, deleting Conversations or overwriting Thread mappings. After the August 26 sunset, recovery is a Responses-side rollback or fix-forward.
Replacement options and limitations
Recommended: Responses API plus Conversations API, with application-owned configuration replacing Assistant objects. Existing reusable Prompts are only a transitional option before their scheduled November 30, 2026 shutdown; move their content into your application code. previous_response_id can be useful for some short-lived chains, but Conversations are the closer match when the application needs a durable server-side container.
Limitations to plan for: manual conversion of history you already retained; item types broader than messages; a new tool loop and event model; possible output differences even with identical instructions; reusable Prompt objects scheduled to shut down on November 30, 2026; and no provider-level rollback to the now-unavailable Assistants API.
The useful “graveyard” lesson
The Assistants API belongs in historical context, but a separate AI tool graveyard would not help a team ship. The reusable lesson is operational: vendor-managed objects can disappear while the user’s session still matters. Keep your own durable session key, version prompts and tool contracts, isolate provider IDs, and preserve a reversible routing layer. This guide is where that history becomes an actionable migration pattern.
Official sources
- OpenAI API deprecations
- Assistants migration guide
- Conversation state
- Function calling
- Production best practices
Bottom line: the Assistants API is already unavailable. Move remaining workloads to Responses now, use Conversations where durable state is required, preserve legacy mappings for audit, and roll back only between validated Responses implementations.
