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

# Versions overview

> Immutable snapshots of agent config produced by each publish or merge.

A **version** is an immutable snapshot of an agent's configuration on a specific [branch](/api-reference/branches/overview). New versions are produced by publishing a [draft](/api-reference/drafts/overview) onto a branch, or by merging a branch into Main. Versions are never edited or deleted — they're the audit trail and the surface conversations actually run against.

A version owns:

* A **config** — the same JSON shape stored in `agent_draft.config`. In this release that's just `{ system_prompt }`.
* A **branch** the version belongs to.
* A **version\_number** unique within that branch, monotonically increasing from 1.
* A **parent\_version\_id** that links to the previous head of the branch (`null` for the very first version on Main).
* A **created\_by** user and a **created\_at** timestamp.

## Allocating version numbers

Both `publish` and `merge` allocate `version_number` under a `FOR UPDATE` row lock on the target branch. Two concurrent publishes (or a publish racing with a merge) on the same branch serialize behind the lock instead of computing the same number and colliding on the unique `(branch_id, version_number)` index. The loser sees its publish/merge succeed against the post-lock state.

## Listing and fetching

* `GET .../branches/:branchId/versions` returns a `VersionSummary[]` sorted newest-first.
* `GET .../versions/:versionId` returns a single `VersionDetail` including the full `config` JSON.
* Each `VersionSummary.created_by` carries the real `{ id, name, email }` of the author, joined from the user table.

## Authorization

Same rules as [Branches](/api-reference/branches/overview): organization-scoped, `404 no_active_organization` when the session has no active org, `404 agent_not_found` for cross-tenant lookups.