> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# Version management

> Publish, promote through environments, compare versions, and rollback safely when needed.

Use versions to track changes, test safely through Sandbox → Pre-release → Live, and rollback instantly if problems occur.

## Quick reference

| I need to...           | Action                                             |
| ---------------------- | -------------------------------------------------- |
| Publish a new version  | Click **Publish** → add description                |
| Promote to Pre-release | **Deployments** → Options → Promote to Pre-release |
| Promote to Live        | **Deployments** → Options → Promote to Live        |
| Rollback               | Find the last good version → Promote to Live       |
| Compare versions       | Select two versions → **Compare**                  |
| View history           | **Deployments**                                    |

## Publishing

Publish a version when you've made changes in Sandbox and want to create a checkpoint, test in a clean environment, or prepare for promotion.

1. Make and test your changes in Sandbox
2. Click **Publish** in the top right
3. Add a clear version description
4. Click **Publish**

A published version includes: FAQs, Sources configs, functions, agent settings, response controls, routing rules, API integrations, and test sets.

> **Tip**
>
> Use descriptive version descriptions. Examples: "Added Spanish language support with new voice", "Fixed booking function timeout", "Updated holiday hours".

> **Note**
>
> Sources content is synced separately. Sync sources before publishing to ensure the latest content is available.

## Promoting

### To Pre-release

1. Go to **Deployments**
2. Click the **Options Menu** next to the version
3. Select **Promote to Pre-release**

Use Pre-release for UAT, validation with select users, and final checks before production.

### To Live

1. Go to the **Pre-release** tab in **Deployments**
2. Click Options → **Promote to Live**
3. Confirm by checking the box and clicking **Promote**

> **Warning**
>
> Promoting to Live affects real customers immediately. Always test in Pre-release first.

You can promote directly from Sandbox to Live, but this is only recommended for emergency hotfixes.

## Comparing versions

1. Go to **Deployments**
2. Select two versions and click **Compare**
3. Review the diff:
   * Green – additions
   * Red – deletions
   * Blue – edits

You can compare FAQs, function code, agent settings, response controls, and routing rules.

## Rolling back

Rollback when a new version has critical bugs, performance degrades, or customer complaints spike. Rollback is just promoting an older version:

1. Go to **Deployments**
2. Find the last known good version
3. Promote it to Live

**Time to rollback:** 2-5 minutes.

After rolling back, investigate the issue, fix it in Sandbox, and re-promote when ready.

## Deployment workflows

### Standard deployment

1. Develop and test in Sandbox
2. Publish with descriptive notes
3. Promote to Pre-release → validate
4. Promote to Live → monitor closely

### Hotfix

1. Reproduce the issue in Sandbox
2. Fix, test, publish
3. Promote through Pre-release briefly, then to Live
4. Monitor closely

### Seasonal updates

1. Apply seasonal changes in Sandbox (hours, policies, etc.)
2. Publish, promote, and schedule for the right date
3. Revert after the season ends

## Best practices

* **Publish regularly** – don't accumulate too many changes in a single version
* **Run [test sets](/agent-studio/testing/simulation-tests) before promoting** – catch regressions early
* **Monitor after promotion** – watch the first 30 minutes closely, check metrics for 24 hours
* **Be ready to rollback** – know which version to revert to before promoting
* **Use consistent descriptions** – consider tags like `[HOTFIX]`, `[FEATURE]`, `[SEASONAL]`

## Automate with the Agents API

If agent promotions belong inside a wider release pipeline, the same publish / promote / rollback actions are available over HTTP.

#### Automate the deployment pipeline via the Agents API

The [Agents API](/api-reference/build-deploy/agents-api/overview) exposes [publish](/api-reference/api-reference/agents/deployments/publish), [promote](/api-reference/api-reference/agents/deployments/promote), and [rollback](/api-reference/api-reference/agents/deployments/rollback) so the same steps can run from CI alongside backend services or infrastructure.

A typical CI job publishes to Sandbox, runs your [simulation testing](/agent-studio/testing/simulation-tests), promotes to Pre-release on success, and blocks promotion to Live behind a manual approval gate.

## Related pages

* [Environments](/agent-studio/deployments/overview) – technical reference
* [Version diffs](/agent-studio/deployments/compare-versions) – comparing changes
* [Project history](/agent-studio/deployments/project-history) – viewing past versions
* [Simulation testing](/agent-studio/testing/simulation-tests) – automated validation
* [Deployments endpoints](/api-reference/api-reference/agents/deployments/publish) – publish, promote, and rollback from code