> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anchorage.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API deprecation policy

> Understand how long API versions are supported, what changes clients must tolerate, and how deprecations and retirements are communicated.

This policy describes how Anchorage Digital evolves its client-facing APIs: what kinds of changes can happen within a supported API version, how long deprecated APIs remain available, and how deprecations are announced. It is written for developers integrating against the versioned REST APIs (`/v2`, `/v3`, `/v4`, ...).

> [!NOTE]
>
> Where an agreement between you and Anchorage Digital specifies different support or notice terms, that agreement governs. This document describes our general practice.

## Compatibility within a version

We do not make breaking changes to a supported API version. When a breaking change is required, we introduce it through a new API version rather than altering the behavior of an existing supported version.

**Additive changes are not breaking changes.** Within a supported version, we may at any time and without notice:

* Add new endpoints
* Add new **optional** request parameters or request body fields
* Add new fields to response objects
* Add new values to enumerated fields that are documented as extensible
* Add new response headers

Clients are expected to tolerate these: ignore unknown response fields and headers, and handle unrecognized enum values gracefully where the field is documented as extensible.

**Breaking changes**—which we will only ship in a new API version—include:

* Removing or renaming endpoints, fields, or parameters
* Changing the type, format, or meaning of an existing field
* Making an optional field required, or tightening validation on existing inputs
* Changing the semantics of an existing operation (e.g. status transitions, error codes for existing failure modes)
* Removing values from an enumerated field
* Changing authentication or authorization requirements for an existing operation

## API lifecycle

Every API version, endpoint, and feature is in one of three states:

| State | What it means |
| :- | :- |
| **Current** | Fully supported. New functionality is added here. |
| **Deprecated** | Still operational and supported for existing integrations. Receives critical bug fixes and security updates, but no new features. A sunset date is published. |
| **Retired** | Past its sunset date. No longer supported and may stop accepting requests. |

When a replacement API version becomes generally available, we announce the deprecation of the version it replaces, publish its sunset date, and provide migration documentation describing the recommended replacement.

## Notice period

When an API version, endpoint, or feature is deprecated, we aim to provide **at least 18 months' notice** before it is retired. Where practical, particularly for major API version changes, we may provide a longer migration period.

During the deprecation period, deprecated APIs remain operational and continue to receive critical bug fixes and security updates. New functionality is generally introduced only in the current supported API version.

After the published sunset date, the deprecated API, endpoint, or feature may no longer be available or supported.

### Exceptions

In exceptional circumstances—including security vulnerabilities, legal or regulatory requirements, third-party service changes, or issues affecting the security or reliability of our platform—we may need to modify or retire an API with less notice. Where possible, we will provide advance notice and migration guidance in these circumstances.

## Beta and preview APIs

APIs, endpoints, or fields labeled **beta**, **preview**, or **early access** are offered for evaluation and feedback. They are not covered by this policy: they may change or be removed without notice and carry no guaranteed support window. An API is covered by this policy once it is designated generally available.

## How deprecations are communicated

Deprecations are announced in the API documentation and changelog. We will also make reasonable efforts to notify registered technical contacts directly.

In addition, deprecation is signaled **in the API itself**, using the standard HTTP mechanisms defined by [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745) (`Deprecation`) and [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) (`Sunset`). Responses from a deprecated API include:

```http theme={null}
Deprecation: @1798675200
Sunset: Fri, 30 Jun 2028 23:59:59 GMT
Link: <https://docs.anchorage.com/migrate/v3-v4>; rel="deprecation"
```

* `Deprecation`—when the deprecation took effect, as a Unix timestamp
* `Sunset`—the date after which the API may stop responding
* `Link` with `rel="deprecation"`—where to find the migration guide

These headers make it possible to detect deprecated integrations automatically—we recommend alerting on them in your HTTP client or API gateway.

As a sunset date approaches, we may schedule brief, announced brownouts (temporary disablement) of the deprecated API to help surface remaining integrations before retirement.

After retirement, requests to a retired endpoint return `410 Gone` where practical, with a `Link` header pointing to the migration documentation.

## Reference

* [v4 API Reference](https://docs.anchorage.com/knowledge-base/api-reference/v4/introduction.md)
* [RFC 9745 — The Deprecation HTTP Response Header Field](https://www.rfc-editor.org/rfc/rfc9745)
* [RFC 8594 — The Sunset HTTP Header Field](https://www.rfc-editor.org/rfc/rfc8594)


## Related topics

- [API reference](https://docs.anchorage.com/knowledge-base/api-reference/v4/introduction.md)
- [Archive a policy](https://docs.anchorage.com/knowledge-base/api-reference/v4/policies/archive-a-policy.md)
- [Policies and approvals](https://docs.anchorage.com/knowledge-base/platform/developers/caas/caas-policies.md)
- [Define a policy](https://docs.anchorage.com/knowledge-base/api-reference/v4/policies/define-a-policy.md)
- [Get a policy](https://docs.anchorage.com/knowledge-base/api-reference/v4/policies/get-a-policy.md)
