Model retirements have become a calendar event. The models behind a production stack now come and go on a regular schedule, and every provider asks the same thing of you: migrate before the shut down date. The hard part is rarely the model itself. It is the migration sprawl that follows when model IDs sit hard-coded across source files, environment variables, CI pipelines, and dashboards, and nobody can say how many places still depend on the retiring model. This playbook covers the vocabulary to get right, an inventory workflow, an alias layer, a testing routine, a staged cutover, and a preflight check that turns the next model deprecation migration into a routine chore.
Why model retirements became routine operations
Providers now ship models faster than most teams can evaluate them, and each new generation pushes older ones toward retirement. All three major platforms frame this as normal operations, not an emergency. OpenAI's deprecations page opens by saying the company "regularly retires older models" and that software relying on its models "may need occasional updates to keep working." Anthropic's model deprecations page says much the same: as safer and more capable models launch, older ones are regularly retired, and applications may need occasional updates. The Gemini API release notes move on a similar rhythm of launches and retirements.
One thing becomes clear from all three: retirement is not a failure of the provider or your team. It is a scheduled event with a date attached, which means it can be planned for, budgeted, and automated like any other maintenance work.
Three ways a deprecation turns into an incident
Most deprecation pain comes from one of three patterns.
1. The blast radius is unknown. Model IDs are versioned dependencies, and they accumulate in surprising places: application code, environment variables, CI configuration, infrastructure-as-code, evaluation scripts, and dashboards. When a notice arrives, the first question is where the ID is used; if answering it takes a scavenger hunt, the migration is already expensive.
2. The vocabulary gets misread. "Deprecated" does not mean "already broken." Both OpenAI and Anthropic describe deprecated models as still functional at announcement time. Teams that hear "broken" over-react; teams that hear "no rush" postpone until the shut down date, when requests start failing and the switch becomes urgent.
3. The replacement is treated as a drop-in. A newer model is not automatically a superset of the one it replaces. Output structure can drift, tool-calling schemas can change, and parameters can be removed. The Gemini API release notes from September 17, 2026 illustrate the point: the entry notes that for teams running tools locally, built-in tool parameters switch to PascalCase and file edits become line-range replacements. A migration that only swaps the model ID breaks those callers.
What "deprecated" means at each provider
Each platform publishes its own vocabulary, and the terms carry specific mechanics worth learning before you plan anything.
OpenAI's deprecations page tracks its deprecated models and endpoints alongside recommended replacements. It defines deprecation as "the process of retiring a model or endpoint." When announced, the model or endpoint immediately becomes deprecated and always carries a shut down date; at that date it stops being accessible. The page uses "sunset" and "shut down" interchangeably, and labels "legacy" models and endpoints as those that no longer receive updates, with the expectation of future deprecation. For teams that truly cannot migrate in time, the page notes that dedicated capacity for continued access beyond a shut down date may be available through the sales team.
Anthropic's model deprecations page uses four lifecycle terms. Active means fully supported and recommended. Legacy means the model will no longer receive updates and may be deprecated later. Deprecated means the model is still functional but no longer recommended, with a published replacement and a retirement date attached. Retired means the model is no longer available and requests to it will fail.
The line that matters most on each page is the same: deprecated models still work. That is exactly why teams misjudge the window, and exactly why the window is the thing to build your process around.
Model deprecation migration: design for the shortest notice window
Notice windows differ by provider and model class, so plan for the shortest window in your stack, not the most comfortable one.
The Claude retirement notice works on an explicit clock: Anthropic states that it notifies customers with active deployments for models with upcoming retirements, "providing at least 60 days' notice before model retirement for publicly released models." Note the frame: notice goes to accounts actively using the model, and the page covers Anthropic-operated platforms. Partner-operated platforms such as Amazon Bedrock and Google Cloud set their own retirement schedules, so a model's status and dates can differ there.
OpenAI announces a deprecation immediately with a shut down date, and its page describes minimum notice periods by model class: at least six months for generally available models, at least three months for specialized variants, while preview models may be retired with much shorter notice, such as two weeks. The page adds that safety or compliance concerns can shorten any of these timelines.
The Gemini API release notes run on a faster drumbeat. According to the official release notes, the September 17, 2026 entry released antigravity-preview-09-2026, "which replaces and deprecates antigravity-preview-05-2026," with the older agent shutting down on October 5, 2026. The same release notes record that the existing gemini-omni-flash-preview endpoint will be deprecated on September 30, 2026. Dates like these shift as plans change, so treat the changelog as the live reference, not this article.
The planning rule that falls out of all three: size your migration process, staffing, and alerting for the shortest notice you can find. If your process can absorb a two-week preview-model retirement, a six-month one is free.
Inventory: hunt every hard-coded model ID
Before touching code, find out where the retiring model is referenced. Treat model IDs as versioned dependencies and search for them the way you would a pinned library version: repository source, environment and deployment variables, CI configuration, infrastructure-as-code, evaluation harnesses, dashboards, and any internal tool that calls the API.
Then reconcile the source-code picture with the provider's own view. Anthropic documents the exact path: open the Usage page in the console, click Export, and review the downloaded CSV, which breaks usage down by API key and model. That export answers what grep cannot: which keys still call the retiring model today. Where the two views disagree, the export wins.
One operational detail while you are in the consoles: notifications from both providers go to accounts and deployments that are actively using a model, so make sure the email address on your billing and account settings is an alias someone owns and monitors.
Decouple call sites with an alias layer
The reason deprecations hurt is that model IDs live at call sites. The fix is structural: make business code reference logical aliases such as summarize, extract-fields, or code-review, and resolve each alias to a concrete model ID in one place, a small registry or configuration file your services read at startup.
When the next notice arrives, migration becomes a mapping-table change rather than a hunt through every service. The registry also records why each mapping exists: which tests it passed, when it was reviewed, what it replaced.
This pattern works cleanly on a single OpenAI-compatible endpoint, which is also why the platform documentation is worth a look while you set it up. String AI's docs describe one base URL (https://www.string.ink/v1) with an OpenAI Bearer-compatible interface, plus a models list interface that reports what a key can access. If you are consolidating several tools onto one endpoint, our guide to running Codex CLI, Claude Code, and Cursor on a single key covers the integration side; the alias layer is its code-side counterpart, and it is the piece that makes future swaps cheap.
Prove the switch on a golden set first
Do not migrate on vibes. Build a fixed golden set of representative inputs from real traffic with expected-output assertions, and run old and new side by side before changing routing. Three failure classes deserve explicit checks.
- Output shape drift. If downstream code parses JSON, extracts sections, or regexes model output, confirm the structure still holds; answers that read fine to a human can still break a parser.
- Tool calls and structured outputs. Agents act on the calls that come back; verify tool-calling payloads are still valid and any structured-output mode still behaves.
- Removed parameters and capabilities. A replacement model is not guaranteed to accept every parameter the old one did, or to support every capability your prompts assume. The test is not whether the new model works, but whether your usage still works on it.
Record results in the registry entry. A failed check deserves a fix or a deferral with a deadline, not silent acceptance.
Cut over gradually, keep the old path in reach
Routing changes deserve deploy-level discipline: send a small slice of traffic first, keep the old ID configured and reachable, and delete it only after smoke tests and error budgets stay clean. Because the alias layer resolves in one place, flipping back is a one-line change rather than a redeploy everywhere.
Once the switch is verified, do the cleanup while the context is fresh: remove the dead model ID from the registry and its entry from the documentation, and delete any temporary circuit breakers added for the transition. Dead IDs and emergency-only code paths are how the next deprecation becomes confusing.
Make the next retirement boring
Two light automations remove most of the remaining surprises.
First, turn "does this model ID still exist?" into a check, not a discovery. At startup or in CI, compare every model ID in your configuration against the endpoint's models list; a missing ID should fail fast instead of surfacing as a production error. The models list interface returns the models a key can access, which makes the comparison a few lines of code.
Second, compare that list on a schedule and alert on changes. A weekly diff of the models list, alongside normal monitoring, flags additions and changes, and catches configuration drift such as an environment still pointing at an old key.
Finally, write a one-page runbook: who evaluates a replacement when a notice arrives, which alias entries are affected, what the rollback target is, and how a switch gets verified. The runbook turns a cross-team scramble into a checklist.
An LLM API migration checklist
- Read the retirement notice and note the shut down date. Deprecated is not yet broken; the date is what matters.
- Pull the provider-side usage export and list every key and service still calling the retiring model.
- Search repositories, CI configs, infrastructure-as-code, and dashboards for hard-coded model IDs.
- Confirm the model ID exists in the endpoint's models list before and after every change.
- Update the alias registry, not the call sites.
- Run the golden set on the candidate replacement; check output shape, tool calls, and parameters.
- Canary a slice of traffic; keep the old model reachable until smoke tests pass.
- Verify with real tasks, then delete dead IDs and temporary fallbacks.
- Record the decision in the registry entry and update the team runbook.
- Schedule the models-list diff so the next notice is never your first warning.
None of this makes retirements disappear. It makes them cheap: one mapping change, one test run, and an alert that arrives before the shut down date instead of after it.
Related reading
- Stop asking every AI model to do everything: assigning research, writing, and review to different models without adding coordination work.
- Developer articles: setup guides and integration notes for the platform.