Assistants API sunsets Aug 26 2026: the Responses migration map

TL;DR

Replace the run lifecycle first (biggest behavioral change: you now own the tool loop). Tool loops are explicitly managed by your code. - Run steps become Items: read response.output for functioncall, functioncall_output, and message items directly. Delete the beta header and beta-namespaced client calls last, so diffs stay reviewable.

When to use

You are seeing this: Status verified 2026-09-26: the Assistants API was deprecated August 26, 2025 and shuts down August 26, 2026. Use this skill when you run into "Assistants API sunsets Aug 26 2026: the Responses migration map".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Migrating from the Assistants API to the Responses API

Status verified 2026-09-26: the Assistants API was deprecated August 26, 2025 and shuts down August 26, 2026. After that date, /v1/assistants, /v1/threads, and /v1/threads/runs stop working.

The concept map

• Assistants become Prompts (configuration: model, tools, instructions), or just parameters on each responses.create call.

• Threads become Conversations: collections of items (messages, tool calls, outputs), not just messages.

• Runs become Responses: one responses.create call replaces the create-run plus poll-run dance. Tool loops are explicitly managed by your code.

• Run steps become Items: read response.output for functioncall, functioncall_output, and message items directly.

What breaks

• There is no automated migration tool from OpenAI. Thread ids do not carry over; you re-create conversation history as input items.

• The OpenAI-Beta: assistants=v2 header goes away entirely.

• Code Interpreter and file search move to Responses built-in tools: tools=[{"type": "file_search", "vector_store_ids": [...]}] and the code interpreter tool. Vector store ids are reused as-is.

• Polling run.status is replaced by awaiting one responses.create, or by polling responses.retrieve(id) for background runs.

Migration order

1. Inventory every assistant id, thread id, and vector store id in the codebase.

2. Replace the run lifecycle first (biggest behavioral change: you now own the tool loop).

3. Move thread history into Conversations or previous_response_id chaining.

4. Delete the beta header and beta-namespaced client calls last, so diffs stay reviewable.

Check before you ship

• Grep the codebase for beta.assistants, beta.threads, and assistants=v2; zero hits is the migration bar.

• Run one end-to-end conversation per migrated assistant and compare outputs.

OpenAI's assistants migration guide states the August 26, 2026 shutdown and the Assistants-to-Prompts, Threads-to-Conversations, Runs-to-Responses, Run-steps-to-Items mapping. The migrate-to-responses guide confirms Responses is recommended for all new projects and that tool loops are caller-managed.