Expiry and retention

Every document has a retention in days. It counts from the document's last update, and 0 means keep forever. The resulting expiry is included in every tool and API response as expires_at (or null for never).

The default

New documents get 30 days unless you say otherwise. Agents are told to surface the expiry when they hand over a link and to set retention_days: 0 for anything worth keeping, so a plain "keep this forever" in your request is enough.

Setting it

• At publish time: retention_days: 0 (forever), retention_days: 7, and so on.
• Later: set_retention(doc_id, retention_days), PATCH /api/docs/{id} with retention_days, or the expiry field in the inspector.
• Home in the app lists your documents expiring within seven days with a Keep button. In the file browser, select several of your documents and use Expiry… in the selection bar.
• POST /api/docs/{id}/keep keeps a document you own with one call; see Keep below for what it does under a policy.

Negative values are rejected. Only the document's owner can change retention; an editor gets a 403.

Updates move the expiry

Expiry is updated_at + retention_days. update_html, update_markdown, update_snippet, put_file, delete_file, set_description, edit_file, apply_patch and restore_version all write a new version and reset updated_at, so a living document that is edited every week with 30-day retention never expires while it is alive. Changing settings alone (visibility, tags, listing, retention, title, alias, folder) does not write a version and does not move the clock. Publishing identical content is a no-op and does not move it either.

The warning email

Three days before a document expires, its owner gets one email: the title, the expiry date, and a Keep this document link. The link is a signed, single-purpose URL on fermium.app; clicking it needs no sign-in and sets the document to keep forever (or to the longest retention your workspace policy allows). A confirmation page says which.

Details worth knowing:

• One email per expiry. If the document is updated afterwards, its clock resets and a fresh warning goes out when it next approaches expiry.
• Documents set to keep forever, documents under legal hold, and documents whose owner's account is disabled are not warned about.
• The link is bound to the document's expiry at the time the email was sent. If retention was changed in the meantime, the link says it is out of date and points you to the app; if the document was already kept forever it says so; if the document was deleted it says so. Nothing else can be done with the link.

Keep

"Keep" means: retention 0, forever. On a workspace whose policy sets a maximum retention, forever is not allowed, so Keep extends the document to that maximum instead. The email link and POST /api/docs/{id}/keep both behave this way, and the response (kept_forever: true or false, plus the new retention_days and expires_at) tells you which happened. Each keep is recorded in the audit log as a retention change.

Workspace policy and retention

On Business and above, a workspace owner or admin can set a minimum and a maximum retention in the workspace policy. The rules:

• A maximum forbids keep-forever: 0 and any value above the maximum are rejected with workspace policy caps retention at N days; 'keep forever' (0) is not allowed.
• A minimum rejects shorter values with workspace policy requires at least N days of retention. Keep-forever still satisfies a minimum unless a maximum also exists.
• These checks apply to set_retention, to PATCH with retention_days, and to a publish that names a retention other than the default.
• A publish that relies on the default (30 days, or no retention_days at all) is not refused. The default is clamped into the window silently: to the maximum if it is above it, to the minimum if it is below.

Agents can read the bounds with get_policy and are told to do so when a publish is refused for policy reasons.

Legal hold

On Enterprise, a document can be put under legal hold. A held document:

• never expires, however its retention is set, and the purge job skips it;
• cannot be deleted (delete_doc and DELETE /api/docs/{id} answer 423 with this document is under legal hold and cannot be deleted; an admin must release the hold first);
• is never purged, even if it was already soft-deleted when the hold was set;
• is left in place when its owner deletes their account;
• gets no expiry warning email.

The document's owner, or a workspace owner or admin, sets and releases the hold with set_legal_hold(doc_id, on) or POST /api/docs/{id}/legal-hold with {"on": true}. Both are recorded in the audit log. GET /api/docs/{id}/policy-state shows whether a document is held, together with its retention and expiry. Release the hold and the normal retention rules resume from where they were.

What happens at expiry

The link stops working the moment expires_at passes: the content host answers with the same neutral not-found page it uses for deleted or nonexistent documents. Nothing distinguishes the three cases to a visitor. The document is still in your list in the app and in list_docs until it is purged, and its retention can still be raised.

Purge

A purge job runs once a day. Expired documents are soft-deleted at that point and enter the same 7-day grace period as documents you delete yourself. After the grace period the files are removed from object storage and the metadata rows are deleted. Nightly database backups roll off 14 days later.

If something expired that you needed, email hello@fermium.app within the grace period with the link. There is no self-serve restore of a purged or soft-deleted document; rolling back to an earlier version of a live document is self-serve, see Versions and history.

Storage

Storage counts the current version of every live document in your workspace against the plan cap. Expired documents still count until they are purged. Deleting or letting documents expire is how you free space; see Plans and limits.