AI API shutdown: complete a migration audit before the deadline
A migration audit plan covering dependencies, control requests, tool calls, streaming, errors, old-versus-new runs, cutover, and rollback.
Changing a model name or Base URL is not a migration. Similar JSON can still behave differently in streaming, tool calls, errors, usage, and limits. Completion requires an official shutdown date, a dependency inventory, behavior comparison, and a reversible cutover.
As of August 25, 2026, OpenAI lists shutdown dates and replacements on its Deprecations page. Its general policy provides at least six months for generally available models, three months for specialized variants, and potentially much less for preview models. Schedule from the specific deprecation entry, not from an assumption.
Record the source and dependencies
Store source URL, check date, old and replacement endpoint/model, shutdown date, and owner. If no date is published, write unknown and assign a recheck; never invent urgency.
Inventory the complete path: endpoint and protocol, model and fallback, payload parameters, tool schema and selection, SSE parser, error handling, prompt version, SDK, services, cron jobs, serverless jobs, n8n or Dify workflows, CI variables, and secret names. Record secret ownership, not secret values.
Build contract tests
Use sanitized real tasks. Cover plain text with required facts, structured JSON, a valid tool call, a case with no tool call, streaming completion, a 4xx request, and a controlled transient failure. Compare contracts rather than exact prose: schema fields, tool name and arguments, application outcome, required facts, stream termination, and retry behavior.
Test streaming separately. Record event shape, termination, usage location, disconnect before and after the first token, and whether retry can duplicate an external action. Do not automatically retry 401, 403, or validation errors. For 429 and transient 5xx, respect Retry-After when present, cap attempts, and add application idempotency for side effects.
Run both paths and classify differences
Run old and new paths against the same fixtures in a test environment. Store case_id, both results, contract pass, difference, and decision. Different wording may be acceptable; changed tool arguments, missing required fields, stream termination, or error semantics require a client fix or an explicit acceptance decision.
For an OpenAI-compatible transport check through BetterToken, use https://www.bettertoken.ai/v1/chat/completions, the user's Bearer key, and a current model ID from Model Plaza or Setup. This validates request format, not behavioral equivalence between models. Create a test key, follow the Chat Completions guide, and record the HTTP status plus a verifiable response field.
Cut over with rollback
Prepare a feature flag or versioned provider config, an owner, an observation window, error and contract-test metrics, a written rollback condition, and the old config without exposed secrets.
Deploy code that understands both contracts, enable the new path for controlled traffic, compare errors and control tasks, expand only when criteria pass, and roll back when a prewritten invariant fails. Remove the old path only after observation and before shutdown. A rollback cannot restore an API after its shutdown date, so leave time for fixes and another cutover.
The audit is complete only with five artifacts: official source and check date, dependency registry with owners, versioned test set and dual-run results, a decision for every material difference, and a cutover/rollback runbook with measurable conditions. A 200 happy path alone remains migration_in_progress.
Sources checked August 25, 2026: https://developers.openai.com/api/docs/deprecations and https://docs.bettertoken.ai/api-reference/chat-completions.