The Guest Manager Public API tiers each endpoint and parameter into one of three stability levels. The level tells you what kind of change to expect over time and how much advance notice we’ll give before changing it.
Stability tiers
Stable
The endpoint or parameter shape is committed long-term. We will not introduce breaking changes within the same major version (v2). Additive changes (new optional fields, new optional response attributes, new endpoints) can happen at any time without notice.
Examples of breaking changes that will not happen on stable endpoints:
- Removing or renaming a documented field
- Changing a field’s type or semantics
- Tightening a previously permissive validation
- Removing a previously valid value from an enum
If we ever need to break a stable endpoint, it requires bumping to v3 with both versions running side-by-side and a documented sunset window.
Preview
The endpoint or parameter shape is published for use but subject to breaking changes during the preview period. Preview surfaces typically cover newer or higher-flux features where customer feedback may surface design issues we want to address before committing.
When we make a breaking change to a preview surface:
- We announce it on the changelog at least 90 days before the change.
- The current behavior continues to work during that window, with
Deprecation: trueandSunset: <date>headers attached to every response. - A
Link rel="deprecation"header points at the migration documentation for the change.
Preview surfaces graduate to stable once we’re confident the shape is right. We do not move backwards from stable to preview.
Internal / undocumented
If an endpoint, parameter, or response field exists in the API but is not in this documentation, treat it as internal. We make no commitments about it; it can change or disappear without notice. Some examples that exist in the codebase but are deliberately unpublished: certain SPA-only convenience endpoints, internal sync metadata, and feature-flagged experiments.
How we announce changes
Every API response that is on a deprecation path includes three headers:
| Header | Value |
|---|---|
Deprecation |
true — the endpoint or behavior is on a deprecation path. |
Sunset |
RFC 8594 HTTP-date — when the deprecated behavior will be removed. |
Link |
<docs-url>; rel="deprecation"; type="text/html" — points at the migration documentation. |
Watch for these headers in your client. If you build alerting on them, you’ll catch breaking-change windows automatically.
For one current example: page[number]= offset pagination is deprecated with Sunset: Wed, 04 Nov 2026 00:00:00 GMT pointing at Pagination.
How we announce additive changes
Additive changes (new fields, new endpoints, new optional parameters) are announced on the changelog page but do not require migration. They are safe to ignore.
What if I’m using a deprecated behavior?
Migrate before the Sunset date. The migration documentation linked from the Link rel="deprecation" header explains the new shape and any tooling we provide for the transition.
If you can’t migrate by the sunset date, reach out to support — we’d rather extend a window than break a customer integration unexpectedly.