> ## Documentation Index > Fetch the complete documentation index at: https://docs.brilo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Versions are branches > How agent versions work in the Brilo API: each version is a branch with a draft and a history of commits, and exactly one version is live for callers. An agent version in the Brilo API works like a branch in git. Each version has a name, at most one unpublished draft, and a history of commits. Exactly one version is live, and inbound calls run its latest commit. Drafts are never heard by callers, so you can change freely and publish when ready. ## What it is An agent version is a named line of settings for one agent, such as "main" or "Holiday hours". Each version holds three kinds of thing: * **Commits.** Every publish adds a commit, a full copy of the settings at that moment. The newest commit is what the version runs. Older commits stay in its history. * **A draft.** Changes you have written but not published. A version has one draft at most. * **Everything the agent uses.** A commit holds the greeting and instructions, and also actions, knowledge bases, workflows and every setting made in the dashboard. One version is **live**. Inbound calls, demo links and calls you place all run the live version's newest commit, chosen at the start of each call. ## When you would use it Agent versions help whenever a change should be checked before callers hear it: * **A small fix.** Update the live version, check the draft, publish. Two calls. * **A bigger change.** Start a new version from the live one, change it over several steps, then make it live in one call. Switching back is one call too. * **Undoing a change.** Restore an earlier commit from the version's history. ## How it works The Brilo API offers one route for each step of that cycle. The table lists them with their MCP tools. | Step | REST | MCP tool | | - | - | - | | See the versions | `GET /v1/agents/{id}/versions` | `list_agent_versions` | | Start a version from another | `POST /v1/agents/{id}/versions` | `create_agent_version` | | Change a version's draft | `PATCH /v1/agents/{id}/versions/{vid}` | `update_agent_version` | | Throw a draft away | `DELETE /v1/agents/{id}/versions/{vid}/draft` | `discard_agent_version_draft` | | Publish a draft | `POST /v1/agents/{id}/versions/{vid}/publish` | `publish_agent_version` | | Make a version live | `POST /v1/agents/{id}/versions/{vid}/go_live` | `set_live_agent_version` | | See a version's commits | `GET /v1/agents/{id}/versions/{vid}/history` | `list_agent_version_history` | | Bring back a commit | `POST /v1/agents/{id}/versions/{vid}/restore` | `restore_agent_version` | | Delete a version | `DELETE /v1/agents/{id}/versions/{vid}` | `delete_agent_version` | `PATCH /v1/agents/{id}` and `POST /v1/agents/{id}/publish` are shortcuts for the live version, so a simple change never needs a version id. A draft starts as a copy of the version's newest commit, with everything it holds. A change then touches only the fields you send. Publishing on the live version reaches callers on their next call, and the commit it replaces moves to history. Publishing on any other version changes nothing for callers until that version goes live. ## Bring back an earlier commit Agent versions keep every commit, so an earlier one can come back. `restore` with a `commit_id` from the version's history makes a new commit with exactly what the earlier one held, including actions and knowledge bases set in the dashboard. History is never rewritten: the commit you replaced stays in history too, so a restore can be undone the same way. A version with a draft is refused with `409 draft_pending` unless you send `discard_draft: true`, so unpublished work is never thrown away by accident. ## Safe to retry Every Agents API verb is safe to repeat. Publishing with no draft, making the live version live, restoring the newest commit and discarding a missing draft each return `200` with the object unchanged and a code in `warnings`, never a second effect. Writes that send a `revision` as `If-Match` (or `if_revision` over MCP) are refused with `409 stale_revision` if the object changed since you read it. ## What else you can do here * [Change an agent through the API](https://docs.brilo.ai/api-reference/agents/quickstart.md), the two call path for the live version. * [Run an A/B test between two versions](https://docs.brilo.ai/agents/ab-test-your-agent.md) in the dashboard. * [Manage versions in the dashboard](https://docs.brilo.ai/agents/versions.md) without code. ## FAQ > **Does creating a new version change what callers hear?** > > No. Creating an agent version copies another version's newest commit and leaves the live > version alone. Callers hear the new version only after you call `go_live` on it. Until then > you can change, publish and test it without any caller noticing. > **Can I restore a commit while a draft is open?** > > Only if you discard the draft. A restore on an agent version with a draft returns 409 > `draft_pending`, so unpublished work is never lost silently. Publish the draft first, or send > `discard_draft: true` once the person you work for agrees to lose it. > **Why can't I make a version live?** > > An agent version needs at least one commit before it can go live, so a version that was never > published returns 409 `version_has_no_commit`. While an A/B test is running, going live returns > 409 `ab_test_active`; end the test in the dashboard first. > **Why can't I delete this version?** > > The live agent version cannot be deleted, because callers would have nothing to reach. The > Brilo API returns 409 `version_is_live`. Make another version live first, then delete this one. > A version in a running A/B test is refused with `ab_test_active`. > **Can I run an A/B test through the API?** > > No. A/B tests between agent versions are set up and ended in the Brilo dashboard. While one is > running, API changes that would disturb it, such as publishing a version in the test or going > live, return 409 `ab_test_active`. A call you place during a test may use either version. > **Should I edit the live version or start a new one?** > > Edit the live version for small changes you can check in one go: the draft is invisible to > callers until you publish. Start a new version for larger work, or when you want to switch > back and forth, because going live and going back are one call each. ## Related * [Change an agent through the API](https://docs.brilo.ai/api-reference/agents/quickstart.md), the quickest path * [API introduction](https://docs.brilo.ai/api-reference/introduction.md), for errors and retries * [MCP tools](https://docs.brilo.ai/api-reference/mcp/tools.md), every version tool with an example This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.