---
title: "Announce deprecation and sunset in headers · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/changes-over-time/deprecation-headers
updated: 2026-10-20
licence: "All rights reserved"
---

# Announce deprecation and sunset in headers

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Required
- Chapter: [Changes over time](https://agentwranglers.se/playbook/api-design/changes-over-time)
- Rule: Mark a retiring endpoint with the `Deprecation` header and its shutdown date with `Sunset`, and link to the migration guide.
- How: 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](https://agentwranglers.se/playbook/website/when-things-break/deprecation-and-sunset) has the full headers.
- Check: `curl -sI https://api.example.com/v1/orders` shows `Deprecation`, `Sunset` and the `Link` to the guide.

Example:

```http
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"
```

**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`.

- Previous: [Version only for breaking changes](https://agentwranglers.se/playbook/api-design/changes-over-time/versioning)
- Next: [Tell clients to ignore what they don't know](https://agentwranglers.se/playbook/api-design/changes-over-time/tolerant-clients)
- [Changes over time](https://agentwranglers.se/playbook/api-design/changes-over-time)