Policy History

Read the version history of your tenant AI policy: every stored version newest first, its lifecycle status, and exactly which fields each version changed.

GET /v1/ai/policy/history returns the version history of the caller's own policy, newest first. Each entry carries the version number, the lifecycle status it was saved under, a changed array naming the fields that differ from the previous version, and the full stored policy document for that version. Together with change_reason recorded at write time, this is the audit trail for "who allowed what, and when": every residency change, every denial, every override is a version.

The changed array is computed against the immediately preceding version, so scanning the list top to bottom reads as a change log without diffing the documents yourself. The first stored version reports its set fields as changed relative to nothing. Versions saved as draft or shadow appear in the history like any other; the status on each entry shows which versions ever bound and which were staged without taking effect.

Only versions this workspace stored appear. A workspace that has always run on the inherited platform default has no versions of its own and reads as an empty list with total: 0, which is the honest answer to "what have we changed": nothing. The platform default itself is not a version of the workspace's policy and is not replayed into its history.

GET/v1/ai/policy/history

Query parameters

limitintegerMaximum number of versions to return, 1 to 200. Values above 200 are clamped; invalid values fall back to the default. Default: 50

Response fields

versions[].versionintegerMonotonic version number of the stored policy.

versions[].statusstringThe lifecycle status this version was saved under: draft, shadow, or active.

versions[].changedstring[]Field names that differ from the immediately preceding version.

versions[].policyobjectThe full stored policy document for this version, in the same shape as the policy field of GET /v1/ai/policy.

totalintegerTotal number of stored versions, independent of limit.

limitintegerThe page size applied to this response.

cURL: Read the last 50 versions

curl "https://api.talonic.com/v1/ai/policy/history?limit=50" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response: Version history

{
  "versions": [
    {
      "version": 2,
      "status": "active",
      "changed": ["region_pin", "denied_models"],
      "policy": {
        "version": 2,
        "status": "active",
        "region_pin": "eu",
        "allowed_providers": ["bedrock"],
        "denied_models": ["claude-opus"],
        "model_substitutions": null,
        "default_models": null,
        "max_attempts": null,
        "model_classes": null,
        "operation_classes": null,
        "features": null
      }
    },
    {
      "version": 1,
      "status": "active",
      "changed": ["allowed_providers"],
      "policy": {
        "version": 1,
        "status": "active",
        "region_pin": null,
        "allowed_providers": ["bedrock"],
        "denied_models": null,
        "model_substitutions": null,
        "default_models": null,
        "max_attempts": null,
        "model_classes": null,
        "operation_classes": null,
        "features": null
      }
    }
  ],
  "total": 2,
  "limit": 50
}

Writes made through this API record the API key as the actor together with the submitted change_reason, so a version in the history stays attributable to an intent, not only to a credential. Supplying a meaningful change_reason on every write is what makes this history useful in an audit two years later.

The history is a read of what was stored, not a rollback mechanism. To restore an earlier configuration, read the policy document of the version to restore and submit it via PUT /v1/ai/policy; the restoration becomes a new version with its own changed set and its own change_reason, which keeps the trail append-only and honest.

AI Policy Overview

Read the Policy

Update the Policy

Policy History

Related