Versioning & stability
The wire major: /v1
The URL prefix is the wire major version. Everything under /v1 evolves
additively — new endpoints, new optional request fields, new response
fields — without breaking existing integrations. A breaking change to the wire
contract would ship as a new prefix, not as a mutation of /v1.
The current release is 1.0.0 (initial release). The OpenAPI spec is committed and versioned with it.
Response enums are closed sets that only grow
The enumerated response values are contracts, not suggestions:
assessment—no_material_concerns|manual_review_recommended|material_inconsistency|assessment_incompletecustomer_disposition—no_customer_concerns_recorded|customer_review_continues|customer_concern_recordedstatus—collecting|pending|processing|completed|failed|erased
No value outside these sets will appear. New values may be added in a future release (announced in the changelog); write your handlers with an explicit default branch so an unknown value degrades safely rather than crashing.
Per-verification wire contracts
Each verification run can pin an explicit wire contract (e.g.
backend-advisory-v0/1, backend-advisory-v0/2) that freezes the behavior of
that Case — the Flow definition, engine profile, and decision policy it ran
under are stamped immutably on the record. A Flow that is live keeps its
version: editing its Template publishes a new version under the same link,
and running Cases are never altered underneath you.
Scorer versions are internal
The engine’s scorer and evidence-schema versions are internal implementation details. They are surfaced in each Case’s audit snapshot (the run-identity record) so a result is always reproducible and attributable, but they are not part of the wire contract — do not branch on them.
The changelog is the record
Every observable change to the API or its vocabulary is recorded in the changelog. If a behavior isn’t documented there or in the committed spec, treat it as internal and subject to change.