---
{
  "id": "platform.sheet.version-history",
  "topic": "sheet",
  "title": "Private workbook version history",
  "locale": "en",
  "version": "2026-08-25",
  "summary": "Workbook history is private and automatically checkpointed; an old version can be restored in place after confirmation or copied safely into a new workbook.",
  "content": "Sheet exposes five private history Actions. `list_versions` pages with `cursor` and bounded `limit`; `get_version` returns a bounded read-only historical preview; `create_named_version` creates a labeled checkpoint; `restore_version` restores selected content in place; and `copy_version` creates a separate workbook from an old version. Historical data may include cells removed from the current workbook, so every version Action has `allow_in_public: false`.\n\nOrdinary Agent mutations already create mandatory automatic checkpoints; do not create a named version for every write. Use `create_named_version` only when the user explicitly asks. It needs no confirmation and supports optional `expectedHeadVersionId` plus `idempotencyKey`. Its registry drift policy is Strict, so a changed head or changed arguments must be reloaded and reconciled rather than silently accepted.\n\n`restore_version` is the only Sheet Action requiring UserConfirm. It requires `workbookId`, `versionId`, and `expectedHeadVersionId`, also uses Strict drift protection, and supports an idempotency key. Restore first saves the current state as a pre-restore checkpoint, then overwrites the current workbook in place with the selected historical content. It does not make the workbook’s integer `version` go backward: successful restore advances current state, so reread the workbook and use the newly returned/current version as the next mutation’s `baseVersion`.\n\nPrefer `copy_version` when the user wants to inspect or recover historical content without replacing the live workbook. It requires `workbookId` and `versionId`, creates a new workbook with fresh history, needs no confirmation, and uses Strict drift handling. Restore remains appropriate only when the user explicitly wants the current workbook changed. Registry schemas, `canRestore`-style runtime results, permissions, confirmation, and typed history errors are authoritative.\n",
  "aliases": [
    "workbook history",
    "sheet version",
    "restore workbook",
    "named version",
    "expectedHeadVersionId",
    "pre restore checkpoint",
    "copy version",
    "版本歷史"
  ],
  "tags": [
    "sheet",
    "versions",
    "restore",
    "confirmation"
  ],
  "relatedActions": [
    "arinova.sheet.list_versions",
    "arinova.sheet.get_version",
    "arinova.sheet.create_named_version",
    "arinova.sheet.restore_version",
    "arinova.sheet.copy_version"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/en/kb/sheet/version-history/"
}
---

Sheet exposes five private history Actions. `list_versions` pages with `cursor` and bounded `limit`; `get_version` returns a bounded read-only historical preview; `create_named_version` creates a labeled checkpoint; `restore_version` restores selected content in place; and `copy_version` creates a separate workbook from an old version. Historical data may include cells removed from the current workbook, so every version Action has `allow_in_public: false`.

Ordinary Agent mutations already create mandatory automatic checkpoints; do not create a named version for every write. Use `create_named_version` only when the user explicitly asks. It needs no confirmation and supports optional `expectedHeadVersionId` plus `idempotencyKey`. Its registry drift policy is Strict, so a changed head or changed arguments must be reloaded and reconciled rather than silently accepted.

`restore_version` is the only Sheet Action requiring UserConfirm. It requires `workbookId`, `versionId`, and `expectedHeadVersionId`, also uses Strict drift protection, and supports an idempotency key. Restore first saves the current state as a pre-restore checkpoint, then overwrites the current workbook in place with the selected historical content. It does not make the workbook’s integer `version` go backward: successful restore advances current state, so reread the workbook and use the newly returned/current version as the next mutation’s `baseVersion`.

Prefer `copy_version` when the user wants to inspect or recover historical content without replacing the live workbook. It requires `workbookId` and `versionId`, creates a new workbook with fresh history, needs no confirmation, and uses Strict drift handling. Restore remains appropriate only when the user explicitly wants the current workbook changed. Registry schemas, `canRestore`-style runtime results, permissions, confirmation, and typed history errors are authoritative.