Guides

An API deprecation policy template

An API deprecation policy tells consumers how much notice they get before something they use is retired (six to twelve months is common for a public API), what a deprecated version still receives, how to ask for more time, and what a retired endpoint returns. The template below covers each part, ready to copy and edit.

By Robert Lasch, Founder · October 26, 2026 · Updated November 8, 2026

A deprecation policy is a promise to your API consumers: how much warning they get before something they depend on goes away. Publish it before you need it, and every retirement after that is a policy being followed, not a negotiation.

Below is a template you can copy, then notes on each choice it asks you to make.

A version moves from current, to deprecated (works unchanged, security and outage fixes only), through a stated notice period such as 6 months, to retired, where it returns 410 Gone.

What goes in an API deprecation policy?

What it covers, how much notice consumers get, how they are told, what a deprecated version still receives, how to ask for more time, and what happens after retirement. The template below has a section for each. Replace everything in square brackets. Delete any section that doesn't apply to you.

# [Company] API deprecation policy

Last updated: [date]

## What this covers
This policy applies to every endpoint, field, parameter and version of the
[Company] API documented at [docs URL]. It does not cover [beta / preview /
internal] endpoints, which may change without notice.

## Definitions
- Deprecated: still works and is still supported, but has a replacement and
  will be retired. Don't build anything new on it.
- Retired (sunset): no longer available. Requests return 410 Gone.

## Notice
- We give at least [6 months] between announcing a deprecation and retiring it.
- Breaking changes to a current version are never made without a new version.
- Security fixes may shorten this window. If they do, we will contact every
  affected client directly.

## How we tell you
- Every response from a deprecated endpoint carries a Deprecation header
  (RFC 9745) and, once the date is set, a Sunset header (RFC 8594).
- We email the technical contact on each affected account when a deprecation
  is announced, and again [30, 7 and 1] days before the retirement date.
- Deprecations are listed in the changelog at [changelog URL].

## Support for deprecated versions
- Deprecated versions receive [security fixes only / security and critical
  bug fixes] until they are retired.
- No new features are added to deprecated versions.

## Extensions
- If you need more time, contact [email] before the retirement date.
- [Role, e.g. the API product owner] may grant an extension of up to
  [90 days], once per client.

## After retirement
- Requests to a retired endpoint return 410 Gone, with a link to the
  migration guide.
- Retired endpoints are not brought back.

How long should the notice period be?

Long enough for your slowest important consumer to plan and ship the change; it is the decision that matters most. Too short and consumers can't plan the work. Too long and old versions pile up.

6 months is a common default for public and partner APIs. It covers one planning cycle for most teams.
12 months suits APIs that large enterprises or mobile apps depend on, where releases are slow.
30 to 90 days can work for internal APIs, where you know every caller by name.

Whatever you choose, make it a minimum, not a fixed date. You can always give more notice.

What support does a deprecated version still get?

Security fixes and fixes for outages, and no new features, is the usual answer. Say it in the policy, because "deprecated" means something different to every team that reads it. Some read it as "will stop working soon", others as "works, but don't build anything new on it".

Bugs: fix only the ones that lose data or block a caller completely. Everything else is a reason to migrate.
Features: none. A new feature on a deprecated version tells consumers they can stay.
Behavior: no changes. A deprecated version should behave the same on its last day as on the day it was deprecated.

How should you handle a request for more time?

Grant it to the one client that asked, with a new date in writing, and only when they show a plan to finish. Decide in advance who can approve one and the longest extension they can give, such as one extension of up to 90 days per client.

Keep a list of the exceptions you granted. If several clients ask for the same thing, the notice period or the migration guide is the problem, and the next retirement should fix it.

Where should the policy live, and how do consumers find it?

On a stable URL in your API docs, linked from the docs home page and your terms. Mention it when you issue a client its first credentials, so it is read before it matters, not after. When the policy changes, date the change at the top and tell existing clients; a shorter notice period should only apply to versions deprecated after the change.

Which changes should the policy call breaking?

Any change that makes a request that worked yesterday fail or mean something different today. List them in the policy, so consumers know what they can rely on and what they should code defensively against:

Breaking: needs notice	Not breaking: can ship any day
Removing or renaming a field, endpoint or parameter	Adding an optional field to a response
Changing a field's type, format or meaning	Adding a new endpoint
Making an optional request field required	Adding an optional request parameter
Changing status codes or error codes clients check	Changing the wording of an error message
Tightening rate limits or validation	Adding a new enum value, if the policy says clients must tolerate unknown values

The last row is the one to decide on purpose. If you want to add enum values freely, say so in the policy and in your docs for each enum, because a client with a strict parser will break on a value it has never seen.

Does an internal API need a deprecation policy too?

Yes, a shorter one. Internal callers break just as hard, and "we'll tell everyone on Slack" stops working once there are more teams than people who remember the integrations. Keep the same sections with smaller numbers: 30 to 90 days of notice, a named owner for each calling service, and a rule that nobody retires a version while a service still calls it without that service's owner agreeing.

What do people forget to include?

What counts as breaking. Say whether adding a field, adding an enum value, or tightening validation counts. Consumers with strict parsers will ask.
Who to contact. A real address that someone reads, not a generic support queue.
The exception process. Someone will ask for more time. Deciding who can say yes before it happens keeps the answer consistent.
Where it lives. Link the policy from your docs home page and from the Link header on every deprecated response.

Sources

Semantic Versioning 2.0.0, which defines a breaking change as one that needs a new major version.
RFC 9745 and RFC 8594, the Deprecation and Sunset headers a policy can promise.
MDN: 410 Gone, for the "after retirement" section.

Where EndPointBlank fits

A policy is only as good as the evidence behind it. EndPointBlank shows which clients still call each deprecated version, sends the Deprecation and Sunset headers from your client library with no code, and reminds affected clients 30, 7 and 1 day before the date. The policy above describes what it does.

See how version lifecycle works or start free. When it's time to retire something, follow how to deprecate an API version.