Skip to main content
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, …).
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: 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 (Deprecation) and RFC 8594 (Sunset). Responses from a deprecated API include:
  • 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