# 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 function_call,
  function_call_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.