Skip to main content
A version is an immutable snapshot of an agent’s configuration on a specific branch. New versions are produced by publishing a draft 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: organization-scoped, 404 no_active_organization when the session has no active org, 404 agent_not_found for cross-tenant lookups.