---
title: "References, retention and version erasure"
description: "References, retention and version erasure"
---

Each retained reference records the file and its version: a record's source, an XLSX format's template and an export's output file. `record_read` and `record_history` return `sourceFileId` with `sourceVersion`; `format_get` returns `templateVersion`. Read the source with `file_read({fileId: sourceFileId, version: sourceVersion})`. Export receipts keep pointing to the version that export wrote. An output reference protects its version from retention and individual version purge, but allows the whole output file to be trashed and purged. Replaying that export with the same `requestId` then fails `not_found`. Source and template files remain protected from whole-file erasure while referenced.

By default, the company keeps all versions. An owner or admin can change `versionRetention` through `organization_update`: `{keep: "all"}`, `{keepLast: N}` to keep the latest N existing versions, or `{keepDays: N}` to keep those created in the last N days. N must be a positive integer. `principal_get` returns the policy in `organization.versionRetention`. Maintenance applies it every five minutes and always preserves the current version and every version pinned by a retained reference.

`purge({fileId, version, confirm: true})` erases one version of an active file. It requires the file's creator, an owner or an admin, plus write access. A pinned version or the file's only version fails with `conflict`. Erasing the current version promotes the latest earlier surviving version, with its content and indexes. Content leaves storage only when no version uses it.

Version numbers are never reused. Retention, version erasure and export rollback can leave gaps in history; `file_history` lists the surviving versions. Always pass the current version as `baseVersion` when writing, without calculating the next version number.