Every change writes an immutable version. Listing the history, restoring an earlier version, and what is recorded.

Fermium never edits a stored file in place. Every mutation writes a new version: a snapshot of the whole file set with a per-file SHA-256, size and content type. Files that did not change point at the same stored object as before, so history costs nothing extra in storage until a file actually changes.

What counts as a version

A new version is written when the content changes:

update_html, update_markdown, update_snippet with different content;
put_file with a new or changed file, and delete_file;
edit_file, apply_patch and write_file;
a save from the browser editor, including an image saved from the image editor;
restore_version;
set_description on a file share (the viewer page is re-rendered);
the automatic poster frame attached after a video upload.

Not a version: changing the title, visibility, password, listing, retention, tags, folder or alias. Those update metadata only.

Publishing identical content is a no-op. The response says changed: false, the version number does not move, and the expiry does not move either. This is what makes "update the document" safe to retry.

Listing the history

list_versions(doc_id) from an agent, or GET /api/docs/{id}/versions, returns every version newest first:

{
  "doc_id": "01J7ZK3N9QW0X4B2C6D8E0F1G2",
  "versions": [
    {
      "version": 3,
      "created_at": "2026-09-15T16:40:03.118204",
      "created_via": "mcp",
      "total_bytes": 48211,
      "current": true,
      "files": [
        { "path": "index.html", "size": 47102, "sha256": "…" },
        { "path": "style.css", "size": 1109, "sha256": "…" }
      ]
    }
  ]
}

created_via records how the version was made: mcp, ui, upload or system. The owner of the document and anyone with edit access can list its history.

Restoring

restore_version(doc_id, version), or POST /api/docs/{id}/versions/{version}/restore, brings an earlier file set back as a new version. History is never rewritten: version 4 might be "the files of version 2", and a rollback is itself undoable by restoring version 3. The URL does not change. Restoring a version identical to the current one is a no-op and the response says changed: false. A snippet or markdown document whose source file had a different name in the old version picks that name up again.

Restoring counts as an update: it resets the retention clock and appears in the audit log.

Prompts that work: "Show me the history of this document." "Go back to version 2." "Undo the last change."

Comparing versions

The inspector's Versions tab lists every version and has a Compare action: pick any two, and each file is shown as changed, added, removed or unchanged; text files get a side-by-side or unified diff, images show before and after, other binary files show their sizes. Restore on either side of the comparison brings that version back as a new version. Details are in Editing in the browser.

From the API, GET /api/docs/{id}/files/{path}?version=n reads a file out of any version, so a client can diff two versions itself; see the REST reference. get_file from an agent reads the current version.

Writing against a version

A write can name the version it was based on. write_file from an agent and PUT or PATCH /api/docs/{id}/files/{path} accept base_version; if the document has moved on, the write is refused with the current version, who wrote it, and a unified diff of that file between your version and the current one, so the writer can merge instead of overwrite. The browser editor does this on every save. See Editing in the browser.

What you can see in every response

version in every tool and API response: the current version number, starting at 1.
changed on update_*, put_file, edit_file and restore_version responses.
list_files and GET /api/docs/{id}: the files in the current version with their sizes and hashes.
GET /api/docs/{id}/manifest?version=n: the file set of any version with each file's SHA-256, size and content type.
The inspector in the app: the full version list with Compare and Restore, plus size, created and updated times.

What is not available

get_file from an agent reads the current version only; use the REST file endpoint with ?version= for an older copy. All versions are kept until the document is purged.

Storage accounting

Your workspace's storage use is the sum of the current version of every live document. Older versions are kept but not counted against the cap today.

Recovery

Alongside each document, a metadata sidecar in object storage mirrors its metadata and full version manifest, excluding password hashes. Together with nightly encrypted database snapshots kept for 14 days, this is how the service is restored after a failure. It is not a user-facing feature; restoring your own earlier version is, see above.

Versions and history