Versioning

URL version

Every route lives under /v1/. Unversioned paths return 404 pointing you at /v1/. Every response carries a Provenance-Version header (a dated release, e.g. 2026-07-01).

Compatibility policy

Within v1 we make no breaking changes. Specifically, we will not:

• remove or rename a field,
• change a field's type,
• change the meaning of an existing enum value,
• add a new required request field.

We may add new optional fields, new endpoints, new enum values, and new error codes — so write forward-compatible clients that ignore unknown fields.

Deprecation

Any breaking change ships under a new major version (/v2/) with at least 6 months notice and a migration guide. v1 keeps running through the notice window.

OpenAPI as source of truth

The API is described by an OpenAPI document that is the contract of record — the SDK and this reference are generated to match it. If the docs and the spec ever disagree, the spec wins.