Changes over time Required

Announce deprecation and sunset in headers

Mark a retiring endpoint with the Deprecation header and its shutdown date with Sunset, and link to the migration guide.

By Erik Bergstedt, Agent Wranglers. Updated 20 October 2026.

How to do it

Send Deprecation as RFC 9745 defines and Sunset as RFC 8594 defines, plus Link with rel="deprecation". The sunset date comes at least six months after the deprecation date for public APIs. After the sunset, answer 410 Gone. The website playbook's deprecation rule has the full headers.

Example

HTTP/1.1 200 OK
Deprecation: @1788220800
Sunset: Tue, 31 Aug 2027 00:00:00 GMT
Link: <https://example.com/docs/migrate-to-v2>; rel="deprecation"; type="text/html"

How to check

curl -sI https://api.example.com/v1/orders shows Deprecation, Sunset and the Link to the guide.

For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/changes-over-time/deprecation-headers.