Versioning
How the contract is versioned, and what may change without notice.
The major version is in the path (/v1). The full contract version is in the OpenAPI document's
info.version; today it is 0.5.0.
Rules every client must follow
- Requests are strict: unknown fields are refused with
422. - Responses may gain fields in a minor version: ignore fields you do not know.
- Stream events may gain types in a minor version: skip types you do not know.
- Open sets (feature ids, error codes, roles) are strings and may grow. Closed sets (such as run status) are enums and change only in a major version.
- Money is a non-negative decimal string, never a floating-point number.
Stability
The contract is a draft until 1.0.0. Until then a breaking change is possible, and always comes with
a new published baseline and a changelog entry. From 1.0.0, breaking changes need a new major version
(/v2), and CI checks every change against the latest baseline.