# Versions

> The version history endpoints of a Layerz model, list, read, compare, pin and restore, and how API clients reach history today.

Every write that changes a model records a version. See [Versions](/docs/concepts/versions).

> [!note]
> These routes authenticate with the web app's session today, not with an API key or an OAuth token. An API client reaches the same history through MCP: `layerz_history`, `layerz_diff` and `layerz_manage_version` (see the [tool reference](/docs/mcp/tools#layerz_history)).

| Method and path                            | Does                                                                   |
| ------------------------------------------ | ---------------------------------------------------------------------- |
| `GET /models/:id/versions`                 | The history within your plan's window, pinned versions always included |
| `POST /models/:id/versions`                | Record a version of the current state (skipped when nothing changed)   |
| `GET /models/:id/versions/:versionId`      | One version in full (`manifest`, `schema`, `inputs`)                   |
| `PATCH /models/:id/versions/:versionId`    | Rename it (`label`) or pin it (`pinned`)                               |
| `POST /models/:id/versions/:versionId`     | Restore it; the current state is saved first                           |
| `GET /models/:id/versions/:versionId/diff` | What changed between that version and the live model                   |

The diff lists items added, removed and modified, and the scenario cells that moved. `?values=true` adds the computed values that changed on the key lines (checks, totals), with `uids`, `branch_id`, `granularity` and `tolerance` to narrow it.
