Versions and updates | Faustine Docs

A version is a numbered, immutable copy of an API: its operations, their schemas and flags, its recipes and its description. An API has one draft, where changes are made, and the versions you published from it. Gateways serve versions and never the draft.

Draft and publish

Every edit to an API goes into the draft: a changed summary or schema, an operation marked as requiring confirmation, an accepted recipe. The draft is what the Operations and Recipes tabs show and what tests run against by default.

Publish in the API's header freezes the draft as the next version. The button shows the number, such as Publish v4, when the draft differs from the latest version. The dialog lists the operations edited and the recipes accepted since then.

Publishing changes what gateways serve. A gateway that follows the latest version switches to the new one. An environment pinned to a version does not change. See Add an API to a gateway.

The Versions tab

The Versions tab lists every published version, newest first.

Column	Shows
Version	The number. The newest has a Latest badge.
Created	When it was published.
Source	The commit the version was analyzed from, when the API comes from a repository.
Ops	The number of operations.
Changes	What changed against the previous version: operations added, removed and changed. A version that removes an operation or changes one incompatibly has a Breaking badge.

Select a row to see its changes by operation. View opens the operations, recipes and description of that version, read-only.

Updates from the code

Three actions in the Actions menu of the API's header bring the API in line with the code.

Action	What it does
Check for updates	Compares the head of the connected branch with the last analyzed commit and updates the API only if it changed. For an API connected to a repository.
Upload a new version	Replaces the stored ZIP and updates only what changed. For an API created from a ZIP.
Re-analyze	Runs the full analysis again over the current code. It uses your model provider like the first analysis.

A re-analysis publishes the next version when it finishes. An update publishes one when the API changed. Environments that follow the latest version switch to it.

A re-analysis keeps your edits to kind and confirmation and your accepted recipes, and refreshes the rest from the code. See The analysis.

After a push, use Check for updates and not Re-analyze. It runs the model only if the API's path changed.

Automatic and manual updates

Under Settings > Keep up to date, Automatic runs the same update on every push to the connected branch and publishes a version when the API changed. Manual leaves it to you. See Keep the API up to date.

What to know before you publish

Consideration	Description
Gateways on the latest version switch immediately	There is no separate deploy step for them. Pin an environment on the gateway to hold it on a version.
A version cannot be edited	To change something, edit the draft and publish again.
The Advanced editor publishes the same draft	Publish in the editor and in the API's header do the same thing.

Next steps

Keep the API up to date: choose between automatic and manual updates.
The analysis: what an analysis reads and writes.
Generate and run API tests: run a suite against the draft before you publish.
Promote from one environment to another: move a version through a gateway's environments.