Versioning
Preview The API versions on two axes so your
integration doesn’t break on a Tuesday. The /v1 in the URL changes only for breaking
shape changes; everything additive is pinned with a dated Forge-Version header.
Pin both and your integration behaves identically until you choose to move.
Two axes: URL major and dated header
Section titled “Two axes: URL major and dated header”/v1 — the URL major
Section titled “/v1 — the URL major”The version in the base path (https://api.managed.dev/v1) is the major version.
It only bumps for a genuinely breaking change to the shape of the API — a field
removed, a type changed, an endpoint relocated. When (if) /v2 ships, /v1 keeps
working for its full deprecation window; you migrate deliberately, not overnight.
Within /v1, the contract is forward-compatible: new fields can appear at any
time. Write tolerant clients — ignore fields you don’t recognize rather than failing
on them — and an additive change is a non-event for you.
Forge-Version — the dated behavior pin
Section titled “Forge-Version — the dated behavior pin”Additive but behavior-affecting changes (a new default, a richer payload, a tightened validation) are gated behind a dated version you pin with a header:
Forge-Version: 2026-06-23This is the Stripe model. Each dated version is an immutable snapshot of behavior. Pin a date and the API behaves as it did on that date, indefinitely — even as we ship newer behavior to callers who haven’t pinned. Omit the header and you float on the latest behavior, which can shift under you.
Per-endpoint stability labels
Section titled “Per-endpoint stability labels”Independently of versioning, every endpoint carries a stability label in the OpenAPI spec, surfaced in the docs and the SDKs:
| Label | What it means |
|---|---|
stable |
Production-ready. Covered by the deprecation policy below; breaking changes require a new URL major and a full window. |
beta |
Functionally complete and supported, but the shape may still change additively within /v1 ahead of stabilizing. Safe to build on with awareness. |
experimental |
Early access. May change or be withdrawn inside /v1 with shorter notice. Don’t depend on it for production-critical paths. |
A label applies to a specific endpoint or field, so a stable resource can expose an
experimental field without destabilizing the rest.
Deprecation policy
Section titled “Deprecation policy”When something must change in a breaking way, it follows a published window rather than disappearing:
- Announce. The change lands in the changelog with a
deprecation date and a migration path. Affected responses carry a
Deprecationheader pointing at the changelog entry. - Overlap. The old and new behavior run in parallel for the full deprecation window, so you migrate on your schedule.
- Sunset. Only after the window closes does the old behavior go away. A request
that pins a removed dated version is served the oldest still-supported
version instead and gets a
Deprecationheader telling you to re-pin — your calls keep working; they just stop honoring the dead pin.
A breaking shape change never happens silently inside /v1 — it requires a new URL
major. The dated header only ever changes additive behavior.