API deprecation guide: timelines, notices, and migration docs

Deprecating an API may look straightforward on paper. You announce the change, let users adjust over time, and retire the old endpoint. But getting every affected customer to migrate before the deadline often proves challenging. Some customers may miss your notice while others will lack the proper know-how to make the switch themselves.

A successful API deprecation strategy accounts for these risks. It gives users enough notice, and it gives them the migration guides they need to switch easily.

This article covers what you need to know about retiring an endpoint and writing a migration guide, so your next update brings customers along instead of leaving them behind.

Key steps in an API deprecation

• Before deprecating an API, set the deprecation and sunset dates, mark the deprecated endpoints in your API reference, and announce the change through channels customers already use.
• Use API usage data to identify customers still relying on the old endpoint and offer help before removal.
• Write a task-oriented API migration guide that explains what's changing, maps old endpoints to new ones, shows before-and-after code, and includes verification steps.
• Mintlify keeps your docs in step with an API deprecation, from auto-generated deprecated labels and side-by-side versioned docs to changelog notices and hidden or redirected endpoints after sunset.

What is API deprecation?

API deprecation is the formal announcement that an API, endpoint, or parameter is being phased out. Users can still use it during the deprecation period, but you've told them to stop building on it and suggested an alternative.

Deprecation and sunsetting aren't the same thing. Deprecation is when you recommend a different option, and the API stays operational, whereas sunsetting is when you decommission it, and it stops working.

For example, you mark GET /v1/orders as deprecated and point users to GET /v2/orders. Nothing breaks yet, and existing integrations keep working while customers move over. Six months later, at sunset, v1 starts returning 410 Gone, and any integration still calling it fails.

How to deprecate an API

An API deprecation follows four steps: set a timeline, mark deprecated endpoints, announce the change, and monitor usage. Together, they tell customers what's changing and when, so your migration guide can focus on how.

Set a deprecation policy and timeline

Start with a deprecation policy that applies to every change, so customers know what counts as a breaking change and what support, fixes, and security updates remain available during the transition.

For example, GitHub's REST API versioning rules state that breaking changes ship in a new, dated version, and the previous version stays supported for 24 months after the new one is released. Requests that name an unsupported version get a 410 Gone response.

GitHub's breaking changes include:

• Removing an operation
• Renaming or removing a parameter or response field
• Adding a new required parameter
• Changing the type of a field
• Removing enum values
• Changing authentication or authorization requirements

Your policy doesn't need GitHub's 24 months, but it should be just as explicit about what counts as breaking.

Then, for each change, set your deprecation and sunset dates. Your policy sets the minimum gap between them, but how far apart they should be depends on how disruptive the change is and how fast your slowest customers ship.

For instance, if you remove a rarely used optional parameter, a short window can work. If you replace an authentication method, something that touches every request from every client, you need far more lead time.

Mobile apps and enterprise integrations often need the most time. Mobile app versions stay on users' phones until users update, and enterprise teams often run changes through review and release cycles.

Mark deprecated endpoints in docs and responses

Make deprecation visible wherever developers interact with the old API, typically where people read and where code runs.

Developers reading your API reference should see the change first. In your docs, set deprecated: true on the operation in your OpenAPI spec. This gives your docs tool a source of truth for displaying its status.

Many developers never open the docs, but their code still calls the endpoint. Reach them in the response itself. The HTTP Deprecation header (RFC 9745) carries the date a resource was or will be deprecated, while the Sunset header (RFC 8594) carries the date it stops working, so client code and monitoring tools can flag the change automatically. GitHub sends both headers on API versions it's about to retire.

Headers catch developers who never read the docs, but they can't explain what to do next. They complement your docs and announcements rather than replace them.

Announce the change where users will see it

Publish an API deprecation notice in your changelog and link directly to the migration guide. Depending on how customers use your API, also consider emailing the owners of API keys that call the deprecated endpoint, in-product notifications, or direct outreach to high-volume customers.

Make the notices actionable and provide high-value information up front. Mintlify's release notes guide puts breaking changes near the top with a clear label, the required action, the deadline, and a link to the migration guide. A deprecation notice follows the same pattern.

Monitor usage before you sunset

Log every call to a deprecated endpoint with the API key that made it. Where possible, identify affected customer accounts and email the largest ones directly rather than waiting until sunset day to find out they missed the notice.

If a major customer still calls the endpoint near the sunset date, contact them directly and ask what's blocking the move. If the blocker is a gap in v2, extend the date until you close it. If the blocker is time or know-how, offer hands-on help, like a migration call or a review of their changes, and keep the date.

How to write an API migration guide

A deprecation notice is the first step in communicating the change, but the API migration guide helps developers transition smoothly to the new API. The most succinct and actionable guides focus on what developers need to do and answer practical questions.

The examples below use an illustrative orders API moving from v1 to v2. The company, endpoints, and dates are fictional, so adapt them to your own API. For broader advice on structuring endpoint pages, see Mintlify's API documentation guide.

Step 1: explain what's changing and when

Start with an overview that explains the change, the dates, and who's affected. A developer scanning the page should quickly see whether it applies to them and the key dates.

Example:

• Deprecated: November 2, 2026
• Sunset: May 3, 2027
• Affected: all /v1/orders endpoints
• Replacement: /v2/orders
• At sunset: v1 requests return 410 Gone

Add one sentence on why. Here, v2 adds cursor pagination and groups customer fields into one object, so results stay consistent when new orders arrive between requests. A reason helps developers decide how much work the migration involves and how soon to start.

Step 2: map old endpoints to new ones

Give developers a direct mapping from the old API to its replacement. Don't make them read two entire reference pages and infer the differences themselves. Use a table to call out differences in request parameters, response fields, authentication, pagination, error codes, and defaults wherever relevant.

v1 endpoint	v2 endpoint	What changes
GET /v1/orders	GET /v2/orders	Cursor pagination replaces page numbers
POST /v1/orders	POST /v2/orders	Customer fields move into a customer object, and qty becomes quantity
GET /v1/orders/{id}/items	GET /v2/orders/{id}	Items return inside the order
DELETE /v1/orders/{id}	POST /v2/orders/{id}/cancel	Canceling replaces deleting

If an old operation has no direct replacement, explain the alternative workflow and call out any behavior that changes with it. For example:

A short note like this keeps developers from finding the difference in production.

Step 3: show before-and-after examples

Your guide should include a representative request to the old endpoint, followed by the equivalent request to the new one.

Before (v1):

POST /v1/orders

{
  "customer_name": "Diana Lee",
  "customer_email": "diana@example.com",
  "items": [{ "sku": "TS-001", "qty": 2 }]
}

After (v2):

POST /v2/orders

{
  "customer": { "name": "Diana Lee", "email": "diana@example.com" },
  "items": [{ "sku": "TS-001", "quantity": 2 }]
}

Explain each difference in a sentence under the code, and add response examples when the response shape changes.

Step 4: give step-by-step migration instructions

Provide a checklist that's easy for developers to follow. For the orders example, the steps might be:

1. Point a test client at the v2 base URL
2. Update request bodies using the mapping table
3. Replace page-number pagination with cursors
4. Fetch items from the order instead of the old items endpoint
5. Replace order deletes with the new cancel endpoint
6. Run your test suite against v2
7. Switch production traffic and watch error rates

When the API allows it, let developers move one endpoint at a time so nobody has to migrate everything in a single release.

Step 5: confirm the migration worked

Give developers a way to make sure the change behaves as they'd expect. You can do this by giving them a test call and describing a good result. For example:

curl -i https://api.example.com/v2/orders \
  -H "Authorization: Bearer $API_KEY"

A successful migration confirms:

• The new endpoint returns the expected status code and response structure
• Required fields are present and correctly parsed
• Authentication, pagination, filtering, and error handling still work
• Integration tests pass in a representative environment
• Production traffic has moved to the replacement endpoint
• Monitoring shows no unexpected increase in errors or failed operations

Finally, tell developers how to verify they're no longer using the deprecated endpoint. That might mean checking API analytics, searching their codebase, reviewing SDK configuration, or confirming request logs after deployment.

Manage API deprecations with Mintlify

As API versions evolve, maintaining the old reference, new reference, announcements, and retirement notices across separate pages becomes increasingly difficult. Mintlify keeps them connected with:

Auto-generated deprecated labels. Mintlify generates API reference pages from your OpenAPI spec and displays a deprecated label when an operation has deprecated: true. The label comes from the same OpenAPI spec that generates your pages, so marking an endpoint deprecated takes one change.

Deprecation callouts on endpoint pages. A label is easy to miss. Add Mintlify's x-mint: content extension to the deprecated operation in your OpenAPI spec to put a callout at the top of its endpoint page with the sunset date and a link to the migration guide. A <Warning> callout makes it stand out from the rest of the reference.

Versioned docs. Add each API version to the versions array in your navigation settings to publish old and new docs side by side, so developers can compare endpoints while they migrate. Tags add badges to the version dropdown, like Deprecated for v1 and Latest for v2.

Changelogs with RSS. Mintlify changelogs include an RSS feed so that users can subscribe to deprecation notices and release updates. Feeds are available on public docs only, and entries strip out code and components. If a deprecation notice includes code samples, add the rss property to its Update component with a plain-text version of the notice. Add tags to your Update components, such as Deprecation, so readers can filter the changelog down to the notices that affect them. Use the changelog guide to set up a consistent place for your notices.

Sitewide banners. To announce a deprecation where every reader will see it, add a banner to your docs.json. It appears at the top of every page, and the warning type gives it an amber background meant for upcoming deprecations. If you make it dismissible, it comes back for everyone when you update its content, such as when the sunset date gets close.

Hide or redirect after sunset. Once an endpoint is retired, decide whether its reference should remain accessible for historical context. Add x-hidden to the operation in your OpenAPI spec to take it out of your navigation but keep the page reachable by URL, or add x-excluded to remove the page entirely. To send anyone who lands on an old v1 page to its v2 replacement, add a redirect in your docs.json.

Frequently Asked Questions

How long should an API deprecation period be?

An API deprecation period should be long enough for your slowest customers to ship a change. The right period depends on your API's stability commitments, customer usage, migration complexity, and the consequences of a failed integration. A change affecting authentication or core business workflows generally warrants more lead time than a minor change to an optional feature.

What's the difference between deprecating and sunsetting an API?

Deprecating announces that an API is on its way out, but it keeps working. Sunsetting turns it off. The deprecation period gives customers time to move to the supported alternative before it's discontinued.

What should an API deprecation notice include?

An API deprecation notice should include the affected endpoints or versions, the reason for the change, the deprecation and sunset dates, the replacement API, a link to the migration guide, and any important compatibility differences. Explain what happens after the deadline and how customers can get help. If the sunset date isn't confirmed, make that explicit.

How do you tell users an API is deprecated?

Use more than one channel. Mark the endpoint in your docs, add Deprecation and Sunset headers to responses, email the owners of keys that still call it, and publish a changelog entry with an RSS feed. RSS entries drop code and components, so give code-heavy notices a plain-text summary with the rss property. Link the migration guide from all four places. Headers are hints, so don't rely on them alone.