Versions and Branches

Every accepted specification is stored as a version. This page explains the versions table, branches, switching the current version and the personal working version.

Versions#

The Versions section of a service page shows the history, newest first: publish date, the version number from the specification's info.version (spec_version), the format version (for example OpenAPI 3.0.3), the branch, a Current badge and colored added/modified/removed counts.

Row actions and who can use them:

Action Who
Show Change Log any user who can read the page
Export (download the specification) any user who can read the page
Use as my working version (pin) any signed-in user
Switch (make current for everyone) admin
Delete (not the current version) admin, editor
Import version admin, editor
Edit the version number (N.N.N) admin
Reparse admin

Reparse re-runs the current parsing and merging logic over a stored version without changing which one is current. It is useful after an upgrade changes how specifications are parsed. If the reparsed version is already current, the merged document is also rewritten.

history_depth controls how many versions are kept per branch. See Configuration Reference.

Branches#

A version belongs to a branch, main unless the publisher says otherwise. See Publishing a Specification. Only versions on the service's main branch become current automatically. Other branches add to their own history without affecting what everyone sees.

The Branch field above the table lists every branch of the service plus its main branch. It defaults to the main branch on each page load and only filters your view.

Personal working version#

The pin button makes a non-current version your working version: all documentation you see, including endpoint pages, tag pages and breadcrumbs, uses it. A banner in the top bar shows "You are viewing your pinned working version" with a button to unpin. The pinned row gets a "Your working version" badge.

A pin is stored per user and per service. If the pinned version is later deleted, you silently fall back to the current one. Global search is not affected by pins.

Branch and version in the URL#

Every documentation address carries branch and version parameters, for example ?branch=main&version=2026-09-20T10-15-00Z_ab12cd34ef56. The version in the address takes priority over everything, including your pin. An unknown version answers 404 rather than silently falling back. An address with neither parameter resolves your pin, then the current version, and is rewritten in place so that copying the address bar later reopens the exact version.

On service, tag and endpoint pages, the branch and version crumbs are dropdowns. Changing the branch jumps to that branch's latest version, and changing the version keeps the branch. If the chosen version lacks the endpoint or tag in the address, a banner explains it and the page falls back to the service page.

Merged snapshots#

Each rebuild also stores a snapshot of the service's merged document. Administrators and editors can promote a snapshot through the API as a low-level rollback. The web interface has no button for it. See API Reference.

Next steps#

Screenshots

Last updated: