Versioning

API versions

Versions are dates. The current version is 2026-11-01.

• Pin a version per request with the X-Verdict-Version header.
• Without the header, a key uses the version that was current when the key was created.
• Every decision records the version that answered it in version.

Additive changes (a new optional field, a new endpoint, a new enum value in a response) ship without a new version. Write clients that ignore unknown fields and unknown enum values. Breaking changes (a removed or renamed field, a changed meaning, a new required input) get a new date, and the old version keeps working for twelve months after the new one ships.

Question-set versions

Each decision runs a versioned question set: the typed questions asked of the decision model, their options and the mapping to answer and reason_code. Versions are dates. Every response records the one that answered in question_set_version.

A new question set ships only with an eval run, and the build fails if precision or recall drops by more than two points. Results per decision and version are on Eval results.

The OpenAPI document

The OpenAPI 3.1 document is generated from the code’s schemas on every change, and these docs are generated from it. A guide that references a field that no longer exists fails the docs build.