# Versions and updates

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](https://docs.faustine.ai/agent-gateway/add-an-api/).

## 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](https://docs.faustine.ai/apis/analysis/#re-analyze).

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](https://docs.faustine.ai/apis/keep-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](https://docs.faustine.ai/apis/keep-up-to-date/): choose between automatic and manual updates.
- [The analysis](https://docs.faustine.ai/apis/analysis/): what an analysis reads and writes.
- [Generate and run API tests](https://docs.faustine.ai/apis/tests/): run a suite against the draft before you publish.
- [Promote from one environment to another](https://docs.faustine.ai/agent-gateway/promote/): move a version through a gateway's environments.