Versioning & Stability

This page states what you can depend on today and, just as importantly, what the platform has not yet committed to. Where a policy is not published, this page says so rather than implying a guarantee that does not exist.

What is contract today

These properties are stable — code against them directly:

• The response envelope. Every JSON success response is { data, meta }, with meta.entitlement_version leading meta. Endpoints add keys after it (for example meta.next on paginated lists).
• Error codes are stable strings. Every error body is { "error": "<code>" } where the code is a stable snake_case string. Existing codes keep their meaning; new codes may be added over time. Parse the exact string and treat an unrecognized code as a generic failure of that HTTP status — never parse the HTTP reason phrase.
• Error codes are machine-discoverable. Each operation's possible codes are published in the OpenAPI document as an x-error-codes extension on its error responses, so you can enumerate them from the spec rather than from prose.
• The path prefix. The customer API is served under the /v1 path prefix.

How contract schemas are versioned

The shared contracts (the four extension points plus the generated customer-API request schemas) carry an explicit versioning policy, quoted from contracts/README.md:

This package is the only shared dependency between the planes — treat changes here as breaking by default.

Versioning: schemas carry $id with a version segment. Additive changes bump minor; anything that changes what a consumer receives bumps the stream epoch (see RBD-4 in conformance/CHECKLIST.md).

In short: additive changes move the minor version, and any change to what a consumer actually receives bumps the stream epoch. Changes to the contracts package are treated as breaking unless proven otherwise by the conformance suite.

What is not yet published

The following are not yet published — do not assume a value for them:

• No deprecation window or removal timeline for the HTTP surface is documented. There is no stated notice period before a breaking /v1 change.
• No availability or latency SLA is published for the customer API.
• No public changelog cadence for the API surface is committed. The authoritative, drift-gated record of the current shape is the OpenAPI document (serving-plane/api/openapi.json) and this reference site generated from it.