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_incomplete
• customer_disposition — no_customer_concerns_recorded | customer_review_continues | customer_concern_recorded
• status — 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.