Deprecation policy

Layer signals every deprecation in the response itself, so an integration finds out from the API rather than from a changelog someone has to read. Nothing is removed without a Sunset date, and the date is always at least 90 days after the deprecation is announced.

This page is the human version of the same policy Layer publishes machine-readably at /api/index.json (interfaces.rest.versioning) and in the OpenAPI description (x-layer-versioning).

What your client should watch for

Signal	Where	Meaning
`Deprecation: @<unix-timestamp>`	Response header, RFC 9745	This operation is deprecated as of that moment. It still works.
`Sunset: <HTTP-date>`	Response header, RFC 8594	The date the operation stops responding. Your migration deadline.
`Link: <url>; rel="deprecation"`	Response header	Migration notes for this specific operation.
`"deprecated": true`	OpenAPI description	The same fact, before you make a call. `x-layer-sunset` carries the sunset date.

A response carrying these headers is otherwise completely normal — same status, same body. Nothing about a deprecation changes behaviour until the sunset date passes, at which point the operation returns 404 NOT_FOUND.

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: <https://www.layer.ai/docs/deprecation>; rel="deprecation"
Content-Type: application/json

Handling it in an integration

Read the headers, don’t parse the version. A path prefix tells you nothing about whether a specific operation is going away; the headers do.
Treat Sunset as a hard deadline. After it passes the operation is gone, not slowed down.
Re-check the OpenAPI description periodically. deprecated: true appears there as soon as the deprecation is announced, so a scheduled diff of /openapi.json catches it without waiting for a live call.

What gets deprecated, and what just changes

Breaking changes ship under a new version prefix rather than changing an existing one — see Versioning. Deprecation is how the old prefix, or an individual operation within it, is retired afterwards.

These are not deprecations and arrive without notice, so build tolerantly:

New endpoints, and new optional request fields.
New fields in responses — ignore what you do not recognise rather than rejecting it.
New enum values, such as a new run status or error code.

These are deprecations and always come with Deprecation + Sunset:

Removing or renaming an endpoint, a field, or an enum value.
Changing a field’s type, or making an optional request field required.
Retiring a version prefix.

Notice period


Minimum notice before sunset	90 days
Announced via	`Deprecation`/`Sunset` headers, the OpenAPI description, and the changelog
Enterprise agreements	May specify a longer window — see your contract