# 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](https://www.layer.ai/api/index.json) (`interfaces.rest.versioning`) and in the [OpenAPI description](https://www.layer.ai/openapi.json) (`x-layer-versioning`).

## What your client should watch for

| Signal                         | Where                                                               | Meaning                                                                        |
| ------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Deprecation: @<unix-timestamp> | Response header, [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745) | This operation is deprecated as of that moment. It still works.                |
| Sunset: <HTTP-date>            | Response header, [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) | 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](https://www.layer.ai/openapi.json)            | 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](/docs/errors).

```plaintext
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

Tip

Log `Sunset` when you see it and alert on it — a deprecation you notice six months early is a scheduled task; one you notice at sunset is an outage.

* **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](https://www.layer.ai/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](/docs/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](https://www.layer.ai/changelog) |
| Enterprise agreements        | May specify a longer window — see your contract                                                          |

Note

Layer’s [MCP servers](/docs/mcp) follow the same policy. A tool being retired is announced in the tool description and in the server’s `tools/list` output before it is removed.