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
Seed — replace with real, sourced deprecation notices as they're announced.
- Confirm your model IDs against the Current Models & Pricing table; if you're on an older ID, plan a migration.
- No other breaking changes recorded here yet. Track the official model docs for the authoritative schedule.