DEV Community

Jangwook Kim
Jangwook Kim

Posted on • Originally published at effloow.com

OpenAI Assistants API Shutdown: Port Your Bot Before Aug 26

#openai #assistantsapi #responsesapi #migration

If your product has a support chatbot, an onboarding assistant, or an internal "ask the docs" helper that was built on OpenAI's Assistants API, you have a dated problem. On August 26, 2026, that API stops answering. Not "gets slower," not "loses a feature." The endpoints return errors, and OpenAI has said there is no extension.

That leaves most teams roughly seven weeks before the cutoff to move a live feature onto different plumbing without changing what customers see. This piece lays out exactly what has to move, shows what breaks quietly if you rush it, and puts a real number on the one cost most migration write-ups skip: the ongoing token bill after you switch.

The short version of what OpenAI is retiring

OpenAI announced the Assistants API deprecation on August 26, 2025, with removal one year later on August 26, 2026. The replacement is two newer building blocks working together: the Responses API (which runs a request and returns output) and the Conversations API (which stores the back-and-forth). Assistant configuration moves into dashboard-managed "Prompts."

The catch that turns this from a config swap into a small project: OpenAI is not shipping a tool to move your existing data. Their migration guide states plainly, "We will not provide an automated tool for migrating Threads to Conversations." So the stored history in your current bot does not follow you automatically. You migrate new conversations forward and decide, case by case, whether old ones are worth backfilling.

If your team also uses OpenAI's Agent Builder or the older Evals platform, note those are on a separate but overlapping wind-down clock. We covered that path in OpenAI Agent Builder and Evals wind-down: a migration checklist.

What actually has to move (the map)

The Assistants API bundled everything into a few server-managed objects. The new model splits those responsibilities apart. Here is the object-by-object mapping straight from OpenAI's migration guide, with what each piece is actually for.

What you had (Assistants) What replaces it What it does now
Assistant (/v1/assistants) Prompt (dashboard only) Holds the model, instructions, and tool list, but you now version it in the dashboard, not by API call
Thread (/v1/threads) Conversation (/v1/conversations) Stores the running history; now holds richer "items," not just messages
Run (/v1/threads/runs) Response (/v1/responses) Executes one request and returns output
Run Step Item A generalized record: a message, a tool call, a tool result

Two changes in that table cause most of the pain, and neither is obvious from a feature list.

First, Assistants could be created and edited through the API; Prompts cannot. They live in the dashboard as versioned profiles. If any part of your system spins up or edits assistants programmatically at runtime, that code has no direct replacement. It becomes a manual, dashboard-configured step.

Second, a Thread stored your history for you; the new setup makes you choose how state is carried. That choice is where the real money question hides, so it gets its own section.

The part that costs money after you switch

With the old Threads, each new user turn sent just the new message. The server already held the rest of the conversation. When you move to the Responses API, you pick one of three ways to keep context between turns:

  1. Re-send the history yourself in each request's input.
  2. Chain with previous_response_id, pointing each call at the one before it.
  3. Attach a Conversation object, so OpenAI stores the items for you again.

The trap: options 1 and 2 both re-bill the earlier turns as input tokens every time. OpenAI's own documentation confirms it for chaining: "all previous input tokens for responses in the chain are billed as input tokens." The Conversation object fixes storage and retention, not the per-turn token bill.

To put a number on it instead of hand-waving, Effloow Lab ran a small OpenAI API check. We simulated a two-turn assistant conversation on the Responses API (/v1/responses, model gpt-5.5-2026-04-23) and measured the input tokens on each turn.

  • Turn 1 sent only the new message: 130 input tokens.
  • Turn 2 carried the prior turn by hand (the common port pattern) plus the new message: 196 input tokens.

Carrying one prior turn cost 66 extra input tokens on the second turn — about half again as much input for that turn (a 51% increase, 196 versus 130). That is a tiny two-turn toy. The gap compounds with every turn, and it grows much faster once tool results (file-search chunks, code-interpreter output) start piling into the history you re-send. The bounded run is a directional check, not a benchmark: it shows the shape of the cost, and the shape is "grows with conversation length."

Why this matters for a budget: under Threads, a long support conversation billed you roughly per new message. Under manual or chained state, a long conversation re-bills its own tail on every turn. For a low-traffic internal tool, shrug. For a customer-facing bot handling thousands of multi-turn chats a day, that is a line item worth modeling before you flip the switch.

Can this survive your workflow?

Before you schedule the migration, check whether these concrete situations describe your product. Each one is a place the port can go wrong quietly.

  • Customer support bot with long threads. State cost and history length matter most here. Decide early: Conversation objects for storage, but budget for re-billed context on every reply.
  • Onboarding or "ask the docs" assistant using File Search. Your vector stores and file-search setup have to be re-wired into the Responses tool shape. Retrieved chunks join the context you carry, so they add to per-turn tokens too.
  • Internal automation that creates assistants on the fly. This is the one that surprises teams. Programmatic assistant creation has no Responses equivalent; those become dashboard-managed Prompts, which may mean a workflow redesign, not a code swap.
  • Anything storing thread IDs in your own database. Those IDs point at objects that stop existing on August 26. You need a plan for the stored references, not just the live code.
  • Compliance or audit needs on stored conversations. Retention rules differ. Response objects default to a 30-day life; items inside a Conversation are not on that 30-day clock. If you rely on longer history, verify where it now lives.

If two or more of these are true, treat the change as a scoped migration with testing time, not a same-afternoon find-and-replace.

When to move now, and when you can wait

Do the port now if: the feature is customer-facing, it uses File Search or Code Interpreter, or your database stores thread IDs. These carry the most hidden work and the least room to fix things after August 26.

You have a little slack if: the assistant is an internal, low-traffic helper with short conversations and no stored state you care about. It still has to move, but the token-cost and history-backfill questions barely apply, so a late, simple re-point is lower risk.

Skip the "wait for a tool" plan entirely. There is no automated Thread migration coming. Planning around one is planning to miss the date.

Bottom line

The Assistants API dies on a fixed date with no auto-migration. The object mapping is mechanical, but two things bite: programmatic assistant creation has no drop-in replacement, and carrying conversation state now re-bills prior tokens every turn. Scope it as a small project, model the token cost for high-traffic bots, and start before August.

Honest limitations of this write-up

A few things this article does not claim, on purpose:

  • We did not migrate a production system. The token check is a synthetic two-turn conversation with a non-confidential prompt. It shows the direction and rough size of the state-carrying cost, not your exact bill.
  • The measured run used the manual-resend pattern only. It did not exercise previous_response_id chaining or a live Conversation object. We lean on OpenAI's documented billing behavior for those, not our own measurement.
  • Latency, real dollar cost, and per-tier pricing are [DATA NOT AVAILABLE] here. Those depend on your model choice, region, and traffic.
  • Exact tool re-wiring (File Search, Code Interpreter) varies by setup. The map tells you what moves; your integration decides how much work each move is.

Those gaps are the reason the piece is useful rather than a marketing claim. The parts we measured, we measured; the parts we didn't, we flag.

What Effloow added

The primary sources give you the mapping and the shutdown date. What they do not hand you is a single view that pairs (a) the object-by-object migration map, (b) a measured token-cost datapoint showing why state-carrying is the expensive part of the port, and (c) a buyer-facing "which of these describes my bot" checklist. That combination (a source map, one honest number, and a decision list) is the contribution here. The measurement is recorded in the public lab note at /lab-runs/openai-assistants-api-sunset-responses-conversations-port-poc-2026.

If you want this kind of dated-migration work done against your own codebase (a scan for the retiring endpoints plus a costed port plan), that is exactly what Effloow's Proof Studio produces, and you can start a scoped request from our services page.

For your engineers

Everything below is implementation detail. The business decision is above; this is the how.

The three surfaces to change per turn

OpenAI's migration guide frames the port as three related changes: send requests to /v1/responses, read output from a typed output array (loop the items, handle message and tool-call items), and pick how you carry state. The state options, with their tradeoffs:

  • previous_response_id: chain each Response to the last. Simplest to bolt on. Re-bills all prior input tokens in the chain (OpenAI's docs state this directly). Also note: the instructions from previous turns are not automatically present in later turns when you chain, so re-assert system behavior as needed.
  • Conversation object (/v1/conversations): attach a conversation to your Response, and items persist server-side, exempt from the 30-day TTL that loose Responses get by default. Closest to the old Thread ergonomically. Storage is handled; per-turn token billing for carried context still applies.
  • Manual input array: you assemble the running history and send it each turn. Most control, most re-billing, and what our lab run exercised.

The endpoints a scanner should flag

If you write a static scan to find migration debt across repos and configs, flag any call to these, since all three stop working on 2026-08-26:

  • /v1/assistants (and SDK equivalents like client.beta.assistants.*)
  • /v1/threads, /v1/threads/{id}/messages (client.beta.threads.*)
  • /v1/threads/runs, /v1/threads/{id}/runs (client.beta.threads.runs.*)
  • Any stored thread_... or asst_... IDs in your database or config

For each hit, the target is: Assistant config → dashboard Prompt; Thread → Conversation; Run → Response; Run Step → Item. Programmatic assistant creation gets a manual flag, because there is no API-level replacement.

Reproduce the token check

The measurement was a two-call run through scripts/openai-lab-run.py against /v1/responses with model gpt-5.5-2026-04-23, max_output_tokens=200, budget-guarded. Turn 1 sent a single new message and reported input_tokens: 130. Turn 2 re-sent the prior user message and assistant reply plus a new message and reported input_tokens: 196. The 66-token, ~51% input-token increase is the carried-state cost for one prior turn; it scales with conversation length and with tool-output size. Full prompts, request IDs, and usage objects are in the public lab note linked above.

Sources

For related token-cost work, see Effloow's OpenAI prompt cache retention cost proof, which measures a different lever on the same input-token bill.

Top comments (0)