REST API
The versioned HTTP API underlying every PolicyVault client — dashboard, SDKs, MCP server, and adapters alike.
PolicyVault's REST API is mounted at /api/v1 on any deployment, self- hosted or hosted. Every client — the web dashboard, the JavaScript and Python SDKs, the MCP server, and the x402/AP2 adapters — is a consumer of this same surface; there is no separate, more-privileged internal API.
Backend is not the security boundary
The backend never holds owner or delegate private keys and never reports a transaction as successful before chain proof. It exposes read/status routes, a lifecycle-aware request pipeline (build → sign → finalize → submit → reconcile), and coordination features (governance, risk, webhooks, audit) — none of which can move funds on their own. See What the hosted server can and cannot do.
Route groups
| Group | Covers |
|---|---|
capabilities, health, metrics | Discovery, liveness, aggregate non-secret operational metrics |
auth | Wallet-session sign-in (hosted mode) |
identities | Machine identity + credential management (wallet-session-only, never reachable by another machine identity) |
vaults | List/get vault state, audit, reconcile |
wallet | The v0.4 request pipeline: build, simulate, sign/approve, finalize, submit, genesis-submit, reject |
organizations | Organization/member/vault-assignment metadata (application-level only — see Owner/agent/approver authority boundaries) |
governance | Policy-change proposal/approval ceremony |
risk | Risk evaluations and released-hold continuation |
manifests | Content-addressed intent-manifest records |
events, webhooks, notifications | Asynchronous state-change notifications (observation only — never authority) |
network | Network/node status, fuel/fee lookups |
audit | Durable, hash-chained event history |
Authentication
Two modes:
- Self-hosted — a single trusted operator on loopback, no hosted sessions, no machine identities required.
- Hosted — a wallet-authenticated session (Schnorr challenge/response) for humans, or a scoped bearer machine credential for automated callers. See Machine identities and capabilities.
Versioning is explicit and fail-closed
Requests, responses, and the covenant version they target are all explicitly versioned. An unrecognized version — of a request schema or a covenant — is refused with a clear error rather than silently reinterpreted under different rules. See API versions.
Idempotency and dry-run
Every mutating call accepts an idempotency key so retries are safe rather than risking a duplicate action. Every mutating call has a corresponding simulate path that runs the real pipeline and reports the real outcome without persisting anything or consuming a gate. See Agent API.
Errors
Every error response carries a stable machine-readable code and a human-readable message, passed back to clients verbatim — never mapped onto a different code or silently upgraded into a success. See Error codes.
See also: Agent API, JavaScript SDK, Python SDK.