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

# Versions

> Immutable snapshots of a shelf's file tree.

A version is an immutable snapshot of a shelf's file tree at a point in time.

## When versions are created

* **Version 1** is created when the processing pipeline completes (or on first approval in review mode).
* **Subsequent versions** are created when you approve a shelf in review mode with file operations (`rename`, `delete`, `mkdir`, `write`).

## Numbering

Versions use sequential integers starting at 1. The `currentVersionNumber` field on the shelf response always reflects the latest version.

## Accessing versions

| Endpoint                                          | Description                              |
| ------------------------------------------------- | ---------------------------------------- |
| `GET /v1/shelves/{id}/versions`                   | List all versions for a shelf            |
| `GET /v1/shelves/{id}/versions/{version}/tree`    | Get the file tree for a specific version |
| `GET /v1/shelves/{id}/versions/{version}/files/*` | Read a file from a specific version      |
| `GET /v1/shelves/{id}/diff?from=1&to=2`           | Compare two versions (unified diff)      |

These endpoints are only available when the shelf status is `ready`.

## Current vs. versioned access

The existing `/tree` and `/files/*` endpoints return the current (latest) state of the shelf. Version endpoints let you access the file tree and contents as they existed at any previous version.