Endpoint lifecycle
Every endpoint carries a maturity stage. It is not a label in prose — it is in the contract, so your tooling can read it.
| Stage | What it means for you |
|---|---|
| Beta | Available, but the contract may still change. Requires an extra scope. Not for production. |
| GA | Generally available. Covered by the versioning guarantee — see Versioning. |
| Deprecated | Still served, on its way out. Responses carry Deprecation and Sunset. |
Reading it from the contract
The OpenAPI document exposes the stage as an x-lifecycle extension on each operation, and deprecated
operations also set the standard deprecated flag. The reference shows it per endpoint, and a generated
client can surface it without asking anyone.
No endpoint is Beta today
Every endpoint of this API is GA: none requires the beta:access scope. The stage stays in the contract
for whatever we add later, and the rule below is how it will work then.
Beta endpoints are gated
Calling a Beta endpoint requires the beta:access scope in addition to the endpoint's own scopes.
Without it the call is refused:
HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
{ "type": "scopes/insufficient", "detail": "Scope 'beta:access' required", … }
That is intentional. It means no one integrates against an unstable contract by accident, and it gives us a precise list of who to warn when a Beta contract moves.
Ask your Staff & Go contact to grant beta:access if you want to try one — and remember to request the
scope explicitly on the token, see Authentication.
Choosing what to build on
For anything in production, build on GA. Beta is for evaluating something that is coming and telling us what is wrong with it while changing it is still cheap.
If a capability you need only exists in Beta, say so. Feedback during Beta is what decides the shape it carries into GA — after that, changing it costs everyone a version bump.