> ## Documentation Index
> Fetch the complete documentation index at: https://artifacts.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```bash CLI theme={"theme":"github-dark"}
  artifacts artifact versions --artifact-id ARTIFACT_ID --limit 20
  ```

  ```text REST theme={"theme":"github-dark"}
  GET /api/artifacts/:artifactId/versions?limit=20
  ```

  ```json MCP theme={"theme":"github-dark"}
  {
    "tool": "list_artifact_versions",
    "input": { "artifactId": "ARTIFACT_ID", "limit": 20 }
  }
  ```
</CodeGroup>

## Read version content

Read the latest source, or a specific version number:

<CodeGroup>
  ```bash CLI theme={"theme":"github-dark"}
  artifacts artifact content --artifact-id ARTIFACT_ID
  artifacts artifact content --artifact-id ARTIFACT_ID --version 1
  ```

  ```text REST theme={"theme":"github-dark"}
  GET /api/artifacts/:artifactId/content?version=1
  ```

  ```json MCP theme={"theme":"github-dark"}
  {
    "tool": "get_artifact_content",
    "input": { "artifactId": "ARTIFACT_ID", "versionNumber": 1 }
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash CLI theme={"theme":"github-dark"}
  artifacts artifact diff --artifact-id ARTIFACT_ID --from 1 --to 2
  ```

  ```text REST theme={"theme":"github-dark"}
  GET /api/artifacts/:artifactId/diff?from=1&to=2
  ```

  ```json MCP theme={"theme":"github-dark"}
  {
    "tool": "diff_artifact_versions",
    "input": { "artifactId": "ARTIFACT_ID", "fromVersion": 1, "toVersion": 2 }
  }
  ```
</CodeGroup>

## Restore a version

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

<CodeGroup>
  ```bash CLI theme={"theme":"github-dark"}
  artifacts artifact restore --artifact-id ARTIFACT_ID --version 1
  ```

  ```text REST theme={"theme":"github-dark"}
  POST /api/artifacts/:artifactId/versions/:versionNumber/restore
  ```

  ```json MCP theme={"theme":"github-dark"}
  {
    "tool": "restore_artifact_version",
    "input": { "artifactId": "ARTIFACT_ID", "versionNumber": 1 }
  }
  ```
</CodeGroup>

## 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:

<Steps>
  <Step title="Resolve the artifact">
    Look it up by path with `artifacts path artifact`.
  </Step>

  <Step title="Read the current state">
    Fetch the latest metadata and version before writing.
  </Step>

  <Step title="Guard concurrent writes">
    Send `expectedLatestVersion` through REST or MCP when other writers may be active.
  </Step>

  <Step title="Describe the change">
    Include a concise `changelog` explaining why the content changed.
  </Step>

  <Step title="Verify before sharing">
    Run a diff before announcing a major update.
  </Step>
</Steps>