Policy Version History

# Policy Version History

> Every change to a policy is versioned. Review the history, diff any two versions, and roll back.

- Human URL: https://conto.finance/docs/policies/versioning
- Raw Markdown: https://conto.finance/docs/policies/versioning.md
- Terminal view: https://conto.finance/ai/docs/policies/versioning

Documentation group: Products

Every change to a policy's definition is recorded as an immutable version. You get a full history
per policy, a diff between any two versions, and one-click rollback. Nothing is overwritten in place,
so you can always see what a policy enforced at any point and restore it.

## What a version captures

A version is a snapshot of what the policy enforces: its name, description, type, scope, priority,
active state, and its full rule set. Assignments (which agents, wallets, or cards a policy applies to)
are tracked separately and are not part of a version.

A new version is appended automatically whenever you:

- Create a policy (`version` 1).
- Change its metadata (name, description, priority, scope, or active state).
- Add, edit, replace, or remove any rule.
- Roll back to an earlier version (the rollback itself is recorded as a new version).

Versions are numbered per policy, starting at 1 and increasing by one. The counter never skips or
reuses a number, even under simultaneous edits.

## List the history

```bash
curl https://conto.finance/api/policies/POLICY_ID/versions \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY"
```

Returns versions newest first, each with its `changeType`, who made the change, when, and a rule
count. Use `limit` and `offset` to page.

## Read one version

```bash
curl https://conto.finance/api/policies/POLICY_ID/versions/2 \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY"
```

Returns the full snapshot for that version, including every rule.

## Compare two versions

```bash
curl "https://conto.finance/api/policies/POLICY_ID/versions/compare?from=2&to=5" \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY"
```

The `diff` reports metadata `fields` that changed and the rules that were added or removed. Rules are
compared by content, so a rule that only moved position is not reported as a change, and an edited
rule shows up as one removed plus one added.

## Roll back

```bash
curl -X POST https://conto.finance/api/policies/POLICY_ID/versions/2/rollback \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "revert the vendor cap change" }'
```

Rollback restores the policy's definition and rules from the target version and appends a new
`ROLLED_BACK` version. The policy type is fixed for the life of a policy and is never changed by a
rollback.

Note:

  Rollback is a change to a live control, so it runs through the same governance approval workflow as
  any other policy edit when your organization requires it. See
  [Governance approvals](https://conto.finance/guides/governance-approvals). If the target version is organization-scoped
  but the policy currently has assignments, rollback is refused until you remove the assignments,
  because organization policies apply automatically and cannot be assigned.

## Audit trail

Version history is a convenience layer for reviewing and restoring policy state. It is separate from
the tamper-evident audit log, which independently records every policy change in a per-organization
hash chain. See [Advanced policies](https://conto.finance/policies/advanced) and the audit integrity section on the
[security page](https://conto.finance/security).