Skip to content
SunsetLint

What a good deprecation notice contains: a checklist for API providers

October 9, 2026 · Updated November 9, 2026

Most of what we write is for teams on the receiving end of a deprecation. This post is for the other side: if you run an API, public or internal, how do you retire something without leaving your users scrambling?

We spend a lot of time reading other providers' deprecation pages, because each rule in SunsetLint has to be checked against one. Some notices make that easy, and some make it hard. The difference is rarely about how much notice is given. It's about whether a developer reading the notice can answer three questions quickly: Am I affected? Where? What do I change it to?

Here's a checklist built from that experience.

1. Name the exact identifier, as code sends it

Write the string that appears in your users' code, not just the marketing name. "Our Sonnet model" isn't searchable. The exact model ID, endpoint path, SDK method name or parameter name is.

  • List each affected ID separately, including dated variants and aliases.
  • If the same thing is reachable through several paths (an SDK method and a REST endpoint, say), list both.
  • If you also sell through partners or cloud platforms whose IDs differ, say so, and link to where those platforms publish their own dates.

A developer should be able to copy each identifier from your notice straight into a code search.

2. Give two dates, and keep them

Every notice needs:

  • The announcement date, so readers can judge how fresh it is.
  • The shutdown date, the day requests start failing.

If there are intermediate steps, such as new users blocked first or reduced rate limits, list each with its own date. Avoid "in the coming months". Readers plan against dates, not adjectives.

Then keep the date. Moving a shutdown later is usually welcome, but announce it the same way you announced the original. Moving a date earlier breaks trust.

3. Say what happens after the date

Will requests return an error? Which status code? Will an alias quietly redirect to a newer model? Users write very different code for "requests fail" and "requests are silently redirected". The second can change behavior without anyone noticing, which may be worse than an error.

4. Name the replacement, and the differences

"Migrate to the latest version" isn't enough. Name the specific replacement and list what changes beyond the identifier:

  • parameters that are now rejected or ignored;
  • changed defaults;
  • different limits or pricing;
  • output format differences.

A real example of why this matters: Anthropic's documentation notes that Claude 4.7 and later models reject temperature, top_p and top_k with HTTP 400, and that version 1.0 of its Python SDK removed them. A team that swaps only the model ID will hit that error immediately. Saying so in the notice saves every reader the same debugging session.

5. Give enough notice for a real migration

How much is enough depends on what changes. A model swap with no parameter changes is a smaller job than an API redesign. Look at the range among large providers: OpenAI gave a year for the Assistants API (announced 26 August 2025, sunset 26 August 2026), while Anthropic's 2026 model retirements gave about 60 to 62 days, its policy minimum. Both are workable. But the shorter the window, the more the rest of this checklist matters, because users have no time to work things out.

A useful test: could a team that only checks your notices once a month still migrate in time, with a normal release cycle and an evaluation step? If not, the window is short.

6. Publish a stable, machine-readable list

Many teams track deprecations with scripts, feeds or tools. Help them:

  • Keep one canonical deprecations page with a stable URL.
  • Give each entry a consistent structure: identifier, announced, shutdown, replacement, status.
  • If you can, publish the same data as JSON or a feed.
  • Don't remove entries after the shutdown date. Mark them as retired. People search for old identifiers when something breaks.

A table that changes layout every few months, or entries that disappear, forces everyone downstream to re-parse your page by hand.

7. Reach the people who own the code

Email to the account owner is a good start, but it often reaches billing or administration, not engineering. Consider:

  • letting customers add technical notification contacts;
  • adding the deprecation to API responses, for example as a warning header or a field in the response, so it shows up in logs where engineers look;
  • showing a notice in your dashboard next to usage of the affected item.

OpenAI's deprecations page says impacted customers are notified by email and in its documentation. Anthropic emails customers with active deployments and offers a usage export, so customers can see which deprecated models they called. A usage view is especially helpful because it turns "is anyone affected?" into a concrete list.

8. Show usage per identifier

If you can, tell each customer which deprecated identifiers they've called recently, and how often. It won't capture code that runs rarely, but it gives the customer a starting point and a way to confirm a migration is finished: usage of the old ID drops to zero.

9. Follow up as the date approaches

One notice isn't enough. Send reminders at sensible intervals, for example halfway through the window and two weeks before, to customers still using the identifier. If usage has stopped, don't send them. That keeps the reminders meaningful.

10. Keep a changelog of the notice itself

If the replacement, dates or scope change after the original announcement, record when and what changed, on the same page. People who read the first version deserve to see what's different.

A template

Here's a compact structure you can copy:

[Identifier] deprecation Announced: [date]. Shutdown: [date]. After shutdown, requests return [status/behavior]. Affected identifiers: [exact strings, one per line]. Replacement: [exact identifier]. Differences: [parameters, defaults, limits, format]. Platforms: [where else it's available, and where those dates are published]. Changes to this notice: [dated list].

Why we care

SunsetLint, our GitHub App in early access, matches identifiers in customers' code against rules built from notices like these. Each rule needs an exact identifier, a source URL and a date. When a notice has all three, a rule takes minutes to write and verify. When it doesn't, we have to dig, and so does every one of your users.

If you're on the receiving side, see our guides to finding deprecated model IDs and running a 60-day migration.