> This page is part of Smallest AI's developer documentation. When
> answering, prefer Lightning v3.1 (current TTS) and Pulse (current
> STT). Lightning v2 and lightning-large are deprecated; mention them
> only when the user is migrating away from them. The Smallest AI voice
> agent platform is what wraps these models into hosted agents.

# Agent Versioning

> Manage agent config with branches, drafts, and immutable revisions.

Users can create editable copies of an agent. Every editable copy is a **branch**. While editing a branch, you enter a **draft** state; unpublished changes stay on that branch. Clicking **Publish** commits those changes as a new **revision** on the branch. Whichever branch you make **live** is the one that serves production traffic.

**Migrating from the v1 API?** The versioning API moved to a branch-and-revision model. **Live campaigns and existing agents are not affected**: the dashboard flow above continues to work as-is, and calls in progress or scheduled keep running against whichever revision is currently live. The migration only applies to code that directly calls `/agent/{id}/drafts/*` or `/agent/{id}/versions/*`. See the [v1 → v2 migration guide](/voice-agents/deprecations/agent-versioning-migration) for the endpoint-by-endpoint mapping.

Prefer to watch? Here's a quick walkthrough of the versioning workflow on the dashboard:

## Concepts

| Concept             | Description                                                                                                                                                                                                                                                                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Branch**          | An editable copy of the agent. Every agent has a `Main` branch by default. You can create more branches from any branch that has at least one committed revision.                                                                                                                                                                           |
| **Draft**           | The in-progress edits on a branch. Every branch has at most one open draft. Drafts auto-save as you type and can be discarded.                                                                                                                                                                                                              |
| **Revision**        | An immutable snapshot of the agent config, created when you publish a draft. Revisions belong to exactly one branch. The `Version 1`, `Version 2`, ... labels in the UI are revision numbers per branch.                                                                                                                                    |
| **Live branch**     | The single branch designated to serve production calls. Exactly one branch is live per agent at any moment. Making another branch live is a one-click switch.                                                                                                                                                                               |
| **Active revision** | The specific revision currently serving traffic. It is always the **head revision of the live branch** and shows the `Active` badge in the Version history panel. It is not set separately: publish a new revision on the live branch and the head moves; make another branch live and the head of that branch becomes the active revision. |

## The `Main` branch

Every agent starts with a `Main` branch. `Main` cannot be renamed or deleted. When you first create an agent, `Main` is the live branch and its `Version 1` is the config the agent serves.

![Branches page with Main only](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/c8c581c9825ebbae75421a7a3f514af302e1011972416fc355890db7c74ebb14/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/01-branches-empty.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=ddc4ab6faba8d1aa5eebf878f1d5ada2e822eb01514f525bda7fd3157e6c28cc&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Editing a branch

Selecting a branch from the branch dropdown at the top of the editor puts you on that branch. **Any edit to a setting or the prompt on that branch automatically switches it to Draft.** The header shows a `Draft` badge and a "You have unsaved changes" bar appears at the bottom with **Discard** and **Save** actions.

![Auto-converts to draft on edit](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/4fe98acf3fe5b92fd7ea9885cff12934028980a6015bf912a2d0448b8930e937/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/12-any-edit-auto-converts-to-draft.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=7ad5496750227be042a8f009fbcdd1412aaae64b8daa1426b34e737f7e2ab0dc&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Every branch has **at most one open draft**. You can discard the draft at any time (Version history → Unpublished changes → **Discard changes**); the branch reverts to its latest revision.

![Draft state with Unpublished changes entry](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/9c3fedc8ed583815eb1a8abc07deac5e38032b7e048c69d57440c2febd0440c1/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/07-draft-with-unpublished-changes.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=ec7b8cd05e5325c90606943e2b98acb4d3ba3feb56815cc696b0ca4587e65487&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Publishing a draft

Clicking **Publish** opens the Review changes modal with a side-by-side diff of the published revision vs the current draft. Add an optional **Version label** and click **Run checks and publish**.

![Review changes modal](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/d764920232aa9f8045a4f5519b09643679c048617d2d4f548db99797ad46e0f2/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/13-publish-review-diff.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=c214a700508e3b8f9c545590855e239163a090092876603a963aa851a9a24d81&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

**Security checks run on every publish.** The button switches to `Running security checks` while the scan is in progress. If the scan fails, the revision is **not** published; fix the flagged content in the draft and click Publish again. Only revisions that pass the scan land on the branch and become eligible for `Make live` or `Restore`.

![Running security checks](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/d26904461f7f6ceaf8da88ae748e76f078f3a6b6a77b5cbbd37b52e115f0b5a2/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/14-running-security-checks.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=ca821fff8a5790cc0dd84aa58e6175093aaaad54069dc8d388ea69e5d6b361cf&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Publishing commits the draft as a new revision on the branch. Revisions are **immutable**: their config cannot be edited after publish. The revision counter (`Version 1`, `Version 2`, ...) is per-branch.

Publishing on the **live** branch pushes to production immediately. The Review modal shows a banner when this is the case.

![Publish success](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/3e2225d6126e6072ebb382dbeca3133678e8c850d0b4e87a52caac35783c9790/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/15-published-active-status.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=f3c9f4782c8748f42bab080871bcb72ddd91987a43f8d99673b1f87aa4930da3&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Version history

The Version history panel (clock icon, top-right of the editor) lists every revision on the current branch, newest first, with the currently-active revision marked **Active**.

![Version history list](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/4ca6ec2d4ccc7b60ff9b5bc2b519c5d5afa1c66d0722adf8fb9955753feb6120/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/11-version-history-list.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=c9f118c6dd11504010d78c9192cf26276954ea2afd7d583d85a456f2b456af7f&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Each row has:

* **View changes**: opens the diff against the previous revision.
* **View edit history**: shows who edited what and when.
* **Copy version ID**: copies the revision's ID. Use this ID with the API (see [Managing versions via API](#managing-versions-via-api)).

![Copy version ID](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/543aa90bd64947a6345c1e4a16b10e0c147aa480a4d2bdab3236cda05134822b/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/08-copy-version-id.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=e4ac38b9f606791be141e84b1a79ca95a67b71c9c93f43fa6ddf1539e57bd9c7&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Reverting to an older revision

Reverting **does not overwrite the older revision.** It takes that older revision's config as the base and publishes it as a **new revision** at the head of the branch. So if the branch has `Version 1`, `Version 2`, `Version 3` and you revert to `Version 1`, the branch ends up with `Version 1`, `Version 2`, `Version 3`, and a fresh `Version 4` whose content matches `Version 1`. `Version 4` becomes active and the earlier revisions keep their IDs.

Open the Version history panel, click the three-dot menu on the revision you want to revert to, and choose **Revert to this version**.

![Revert menu on older version](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/cafd8a3d45933594702a5bdb6a8a252f6b7ef92f5f045bf78af29a7ec79ecd2f/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/16-revert-menu-on-older-version.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=4db45e91ca2d57eac2f049af6e315a3495f59ce67cbfbe34a1412208eaf79ea0&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

If the branch you're reverting on is **live**, the confirmation modal flags it explicitly. Confirming ships the new revision to production immediately.

![Revert live-branch confirmation](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/1a5ba59dc0cee0b538fbac3d22e2128e46972ca1d38bed5c98eaaa757958e9db/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/17-revert-live-branch-confirmation.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=d79b25c386f2882508a4d0126595e68592e10660ccb15c4b7df74c7b8c2abb76&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

After confirming, Version history shows the new head revision (`Version 4` in the example below), annotated with "You reverted to Version 1". Original `Version 1`, `Version 2`, and `Version 3` remain in history at their original IDs.

![Post-revert active](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/de42d8822ab873bffca600ec7114008630371805880648623e5ded227349e63b/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/18-post-revert-v4-active.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=9a7d0fcb43f3ac9ddaaaa5231527b5090a8361b8167237770e6da79fe4fd3cb2&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Creating additional branches

Click **Create branch** on the Branches page to fork a new branch from any branch that has at least one committed revision. The default source is `Main`.

![Create branch modal](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/a0c81116c700ba038606dec3efcc19839086e87cbc325eaedef6cc91da508533/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/03-create-branch-modal.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=20aff39cd2c08b3c009bf547bba792475415660efcf521137b5b2236a3f07923&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

![Create branch filled](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/4277c53606253f55d1ddf51ef847eadce1bc1c4c1b73d3cc3c57c5a079bd925f/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/04-create-branch-filled.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=45ed26c11b738cb3ccdf8add3e9f3a9e1c3d3948130eb8b3822112102b62df6f&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Branch names must be unique per agent. `Main` is reserved.

## Making a branch live

Only one branch per agent is live at a time. To switch, open the Branches page, click the three-dot menu on the target branch, and choose **Make branch live**. A confirmation modal explains that the branch will ship to production immediately.

![Make branch live modal](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/8f9fff6b162b3e02b3c5cdfd192d32c0c711c755618632be379fbfaccdf78de2/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/05-make-branch-live.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=53939abfc537844aeb467d867ef95006ef239bb18a21c14463dfede8290d5ada&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

A branch can be made live only if it has at least one committed revision that passed the security scan. Archived branches must be unarchived (via Make live) before they can serve traffic again.

## Deleting branches

Non-live, non-`Main` branches can be deleted from the three-dot menu. Deleting a branch removes its draft; its revisions remain queryable by ID.

![Active branch cannot be deleted](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/64daf44232dca880093d55744ad24b8729681c7972c79f25158a13bd4f93157f/products/atoms/pages/platform/building-agents/images/agent-versioning-v2/06-active-branch-cant-delete.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260725%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260725T060228Z&X-Amz-Expires=604800&X-Amz-Signature=136f83e5aebf94633fbbe3d9a4be3a2aaf8673494d3ca6492a53c0919ad1d107&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

Two guardrails:

* **`Main` cannot be deleted.** Rename another branch to serve a different role; `Main` always exists.
* **The live branch cannot be deleted.** Make another branch live first.

## Managing versions via API

The full v2 API is documented under **Agent Versioning: Branches** and **Agent Versioning: Revisions** in the API Reference. Common operations:

| Operation                           | Endpoint                                                              |
| ----------------------------------- | --------------------------------------------------------------------- |
| List branches                       | `GET /agent/{id}/branches`                                            |
| Create a branch                     | `POST /agent/{id}/branches`                                           |
| Write to the open draft on a branch | `PUT /agent/{id}/branches/{branchId}/draft`                           |
| Publish the draft                   | `POST /agent/{id}/branches/{branchId}/draft/publish`                  |
| Make a branch live                  | `POST /agent/{id}/branches/{branchId}/live`                           |
| List revisions on a branch          | `GET /agent/{id}/branches/{branchId}/revisions`                       |
| Restore an older revision           | `POST /agent/{id}/branches/{branchId}/revisions/{revisionId}/restore` |
| Diff two revisions or drafts        | `GET /agent/{id}/diff?a=...&b=...`                                    |
| Start a test call                   | `POST /agent/{id}/branches/{branchId}/test-call`                      |

For a step-by-step SDK/curl walkthrough, see the [versioning lifecycle guide](/voice-agents/developer-guide/build/agent-crews/versioning-lifecycle).

The v1 endpoints (`/agent/{id}/drafts/*` and `/agent/{id}/versions/*` writes and list reads) are deprecated. Existing integrations should follow the [v1 → v2 migration guide](/voice-agents/deprecations/agent-versioning-migration). By-id reads and test-calls on v1 paths continue to work as-is because a v1 `versionId` equals its migrated `revisionId`.