Skip to main content
apiguide.dev

Deprecation Header

Signals that an endpoint or resource is deprecated and may be removed in future.

Header TypeResponse Header
SpecificationStandard RFC compliant
Associated CodesNone

What is the Deprecation header?

The Deprecation response header, defined in RFC 9745, tells clients that the resource they are using is deprecated. Its value is either the boolean true for an already-deprecated resource, or an HTTP-date announcing when deprecation takes (or took) effect.

API Usage & Best Practices

  • Give consumers warning: Emit the header well before removal so integrators have time to migrate away from the endpoint.
  • Pair with Sunset: Combine it with a Sunset header to state when the resource will actually stop working, giving a concrete deadline.
  • Link to guidance: Add a Link header with rel="deprecation" pointing to documentation that explains the replacement and migration path.

Examples

HTTP/1.1 200 OK
Deprecation: Wed, 01 Jul 2026 00:00:00 GMT
Sunset: Sat, 31 Oct 2026 23:59:59 GMT
Link: <https://api.example.com/docs/v2>; rel="deprecation"

Associated HTTP Status Codes

No specific HTTP status codes are explicitly tied to the usage of the Deprecation header in our reference yet.

Sponsors

Support the project →