Version history

List versions, read source content, compare diffs, and restore old snapshots.

Every write is kept as an immutable version. The artifact points at the latest one, while older versions stay addressable for history, diffs, and restores.

List versions

CLI

artifacts artifact versions --artifact-id ARTIFACT_ID --limit 20

Read version content

Read the latest source, or a specific version number:

CLI

artifacts artifact content --artifact-id ARTIFACT_ID
artifacts artifact content --artifact-id ARTIFACT_ID --version 1

The REST route returns raw source text with helpful headers:

Header	Meaning
content-type	Source content type, e.g. text/markdown; charset=utf-8
x-artifact-id	Artifact ID
x-artifact-version	Returned version number
x-content-type-options: nosniff	Prevents browser content-type guessing

Compare versions

CLI

artifacts artifact diff --artifact-id ARTIFACT_ID --from 1 --to 2

Restore a version

Restoring never mutates old versions. It creates a new head version whose content comes from the version you selected.

CLI

artifacts artifact restore --artifact-id ARTIFACT_ID --version 1

Retention

How long version history is kept depends on your plan:

Plan	Version history
Free	30 days
Pro	365 days
Team	365 days

A reliable agent loop

For agents that update the same artifact repeatedly:

1. Resolve the artifact

   Look it up by path with artifacts path artifact.

2. Read the current state

   Fetch the latest metadata and version before writing.

3. Guard concurrent writes

   Send expectedLatestVersion through REST or MCP when other writers may be active.

4. Describe the change

   Include a concise changelog explaining why the content changed.

5. Verify before sharing

   Run a diff before announcing a major update.