API stability and lifecycle

API endpoint prefixes communicate their stability tier and retirement commitments. Use stable endpoints for production integrations whenever they are available.

We do not introduce backwards-incompatible changes to an endpoint while it is served. Additive changes, such as new optional response fields, may be introduced without changing its version.

When a change cannot be made compatibly, we publish it at a new versioned path.

Stable endpoints use the /v1/ prefix and are recommended for production integrations. They receive at least one month of retirement notice.

Preview endpoints use prefixes such as /v1preview1/. They are intended to become stable, but still may be revised. They receive at least one week of retirement notice.

The number at the end of a preview prefix distinguishes successive preview versions. For example, an incompatible revision can be published under /v1preview2/.

Experimental endpoints use prefixes such as /v1experimental1/. We provide no guarantees for experimental endpoints; they may change or be removed without notice.

We mark preview and stable endpoints as deprecated before retiring them, following the minimum notice period for their stability tier.

Responses from a deprecated endpoint include both lifecycle headers:

• The RFC 9745 Deprecation header, for example Deprecation: @1782863999, communicates when the endpoint became or will become deprecated.
• The RFC 8594 Sunset header, for example Sunset: Wed, 11 Nov 2026 23:59:59 GMT, communicates when the endpoint is scheduled for retirement. The endpoint is guaranteed to be served until that time.

Migrate to the replacement endpoint before the sunset time. The endpoint may stop being served after that time has passed.