API versions
How PolicyVault versions its API, covenant, and request schemas, and why unknown versions always fail closed.
PolicyVault versions several independent things, and treats every one of them with the same rule: an unrecognized version fails closed, with no default and no cross-version fallback.
What is versioned
- The API itself (
/api/v1) — the REST surface's own version. - The covenant protocol — the on-chain contract version a vault runs on (see Covenant enforcement). Covenant versions are additive and frozen: an earlier version is never mutated in place, and a vault on one version is never silently upgraded to another.
- Request/response schemas — mutating request bodies carry an explicit schema version. A client speaking a different wire shape gets a clean refusal (
SCHEMA_VERSION_UNSUPPORTED) instead of the server silently reinterpreting the body under different rules. - The MCP protocol revision — the MCP server implements specific, named protocol revisions and negotiates explicitly during initialization rather than guessing a client's capabilities.
Why this matters
Fail-closed versioning is a direct funds-safety property, not just an engineering nicety: if an unrecognized version were ever routed to a "best guess" default handler, a client or server running mismatched assumptions about what a field means could build or accept a transaction neither side actually intended. PolicyVault refuses instead.
Discovering what a deployment supports
Every deployment publishes a capability-discovery document (fetchable without authentication) describing exactly which covenant versions, schema versions, actions, and feature flags it supports. Every official client — the dashboard, the SDKs, the MCP server — reads this document rather than hardcoding assumptions about a specific deployment, so an integrator should do the same rather than assuming any specific deployment supports every feature described in this documentation.
Current production covenant
The hosted production deployment runs the policyvault-0.4.1 covenant protocol — see the version history in Covenant enforcement and the project's own CHANGELOG.md for what changed between versions and why.
See also: REST API, Supported networks.