Deprecation & Migration Watch
Models get retired, parameters get renamed, behaviors shift. This page tracks breaking changes so upgrades don't surprise you. If you build on the API, skim it periodically.
Why this matters
A pinned model ID will eventually be deprecated and then removed. Code that hard-codes it breaks. A little hygiene prevents 2am surprises.
Survival rules
- Read model IDs from config, never scatter literals across the codebase — then migrating is a one-line change.
- Watch announcements for deprecation dates and recommended replacements.
- Re-run your evals when you switch models — behavior can shift even on a "newer, better" model.
- Test before the deadline, not after removal.
Common kinds of change
| Change | Example | What to do |
|---|---|---|
| Model retired | An older model ID stops working | Move to the recommended successor; re-eval |
| Parameter superseded | A reasoning/budget knob replaced by effort | Update calls; see Thinking & Effort |
| Default shift | A new default model/behavior | Pin intentionally; verify your prompts still work |
| Endpoint/SDK update | New SDK major version | Read the migration guide; bump deliberately |
Current watch
The authoritative schedule lives on the official model deprecations page — confirm dates there before you migrate. Anthropic gives at least 60 days' notice before retiring a publicly released model.
Deprecated models
| Model ID | Deprecated | Retires | Move to |
|---|---|---|---|
claude-opus-4-1-20250805 (Opus 4.1) | June 5, 2026 | August 5, 2026 | claude-opus-4-8 |
Requests to a model past its retirement date fail — if you pin Opus 4.1, migrate before the deadline.
Recently retired
claude-opus-4-20250514 (Opus 4) and claude-sonnet-4-20250514 (Sonnet 4) were retired June 15, 2026. Calls to those IDs now error — move to claude-opus-4-8 and claude-sonnet-5 respectively.
Parameter deprecations
On Claude Opus 4.7 and later (including Opus 4.8 and Opus 5) and on Claude Sonnet 5, the sampling knobs temperature, top_p, and top_k are deprecated: setting any of them to a non-default value returns a 400 error. Omit them and steer behavior with prompting and Thinking & Effort instead.
Always confirm your model IDs against the Current Models & Pricing table; if you're on an older ID, plan a migration.