Versioning

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

/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

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-23

This is the Stripe model. Each dated version is an immutable snapshot of behavior. The header is optional: pin a date and the API behaves as it did on that date — even as we ship newer behavior to callers who haven’t pinned. Omit the header and you get the latest behavior, which can shift under you. Send an unknown date and the request fails with a 400, so a typo’d pin surfaces immediately instead of silently floating.

Whichever version serves your request is echoed back in the Forge-Version response header on every response — pinned or not — so you can always confirm what you got. The current dated version is 2026-06-23.

Always pin in production

Send Forge-Version on every request from CI and production services. It’s the difference between a deterministic integration and one that changes behavior the day we ship a new default. Bump the date deliberately, after reading the changelog and testing. The Go SDK pins its tested version on every request for you.

Surface stability: X-Forge-Stability

The API does not label individual endpoints stable, beta, or experimental. Instead, the stability of the surface as a whole is reported on every response:

X-Forge-Stability: preview

The API is currently in developer preview: the surface is live and real, but endpoints, scopes, and payloads may still change ahead of general availability, on shorter notice than the deprecation policy below will guarantee once the header reports a stable surface. Read the header rather than assuming — when the preview label drops, it drops for the whole surface at once.

Deprecation policy

When something must change in a breaking way, it follows a published window rather than disappearing:

1. Announce. The change lands in the changelog with a deprecation date and a migration path.
2. Overlap. The old and new behavior run in parallel for the deprecation window, so you migrate on your schedule.
3. Sunset. Only after the window closes does the old behavior go away.

A breaking shape change never happens silently inside /v1 — it requires a new URL major. The dated header only ever changes additive behavior.

Next steps

ChangelogDated versions, what each one changed, and deprecation notices.

Requests & responsesSending the Forge-Version header on every call.

SDKsThe Go SDK pins its tested Forge-Version on every request.