> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aui.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Versions

> An agent's behavior, versioned: draft, publish, roll back.

A **version** is a snapshot of an agent's configuration. Versions move through
a simple lifecycle:

```
draft  ──publish──▶  published (live)  ──publish another──▶  still published
                          │
                       archive (only when not live)
```

* **Draft** — editable. Push configuration to it as often as you like.
* **Published** — frozen. Exactly one published version is the agent's **live**
  version, the one conversations run against.
* **Archived** — retired from everyday use.

***

## Create a draft version

```bash cURL theme={"dark"}
curl -X POST "https://api-v3.aui.io/apollo-api/management/v1/agents/{agentId}/versions" \
  -H "Content-Type: application/json" \
  -H "x-organization-api-key: <org_api_key>" \
  -d '{ "source": "version", "from_version": "6b455e297e4271a82fd73fc7", "label": "checkout-flow-v2" }'
```

### POST `/management/v1/agents/{agentId}/versions`

<ParamField body="source" type="string" required>
  Where the draft starts from: `empty`, `template`, or `version` (clone an
  existing version).
</ParamField>

<ParamField body="from_version" type="string">
  Required when `source` is `version` — the version to clone.
</ParamField>

<ParamField body="from_template" type="string">
  Required when `source` is `template`.
</ParamField>

<ParamField body="label" type="string">
  Free-form label for your own bookkeeping.
</ParamField>

<ParamField body="tags" type="array">
  Free-form tags.
</ParamField>

<ParamField body="notes" type="string">
  Notes shown alongside the version.
</ParamField>

<ResponseExample>
  ```json 201 theme={"dark"}
  {
    "id": "6c566f3a8f5382b93fe84fd8",
    "agent_id": "6a344d186d3160971ec62eb6",
    "version_number": 4,
    "version_revision_number": 0,
    "version_tag": "v4.0",
    "status": "draft",
    "parent_version_id": "6b455e297e4271a82fd73fc7",
    "label": "checkout-flow-v2",
    "tags": [],
    "created_at": "2026-07-13T14:02:11Z",
    "published_at": null
  }
  ```
</ResponseExample>

***

## List versions

### GET `/management/v1/agents/{agentId}/versions`

Lists the agent's versions as a [paginated
list](/api/management/projects#pagination), filterable by:

<ParamField query="status" type="string[]">
  `draft`, `published`, `archived`.
</ParamField>

<ParamField query="tag" type="string">
  Partial match on the version tag (e.g. `v3`).
</ParamField>

<ParamField query="version_number" type="integer">
  Exact match.
</ParamField>

<ParamField query="label" type="string">
  Partial match on the label.
</ParamField>

<ParamField query="exclude_revisions" type="boolean">
  Only return base versions (revision 0).
</ParamField>

## Update a version

### PATCH `/management/v1/agents/{agentId}/versions/{versionId}`

Updates a version's metadata — `label`, `tags`, `notes`. The configuration
itself changes through [push](#push-a-configuration-bundle), never here.

***

## Publish a version

### POST `/management/v1/agents/{agentId}/versions/{versionId}/publish`

Makes this version the agent's **live** version. One verb covers the whole
story:

* Publishing a **draft** freezes it, then makes it live (shipping).
* Publishing an **already-published** version re-activates it (rolling back or
  switching).

Returns the now-live version.

## Archive a version

### POST `/management/v1/agents/{agentId}/versions/{versionId}/archive`

Retires a version from everyday use. The live version can't be archived —
publish another version first.

***

## Push a configuration bundle

Upload configuration to a version, committing a new revision:

```bash cURL theme={"dark"}
curl -X POST "https://api-v3.aui.io/apollo-api/management/v1/agents/{agentId}/versions/{versionId}/push" \
  -H "Content-Type: application/json" \
  -H "x-organization-api-key: <org_api_key>" \
  -d '{
    "caller": "cli",
    "commit_message": "Tighten the dispute-window rule",
    "bundle": { "schema_version": "1", "general_settings": { ... } }
  }'
```

### POST `/management/v1/agents/{agentId}/versions/{versionId}/push`

<ParamField body="caller" type="string" required>
  What is pushing: `agent_builder`, `ui`, or `cli`.
</ParamField>

<ParamField body="commit_message" type="string">
  Describe the change (up to 4000 characters).
</ParamField>

<ParamField body="bundle" type="object" required>
  The versioned agent configuration bundle. Must include `schema_version` and
  `general_settings`. The bundle is validated before it's committed — invalid
  configurations return a `422` with field-level details.
</ParamField>

The response carries the new revision's identity and content digest
(`new_version_tag`, `revision_id`, `sha256`, `size`).

## Pull a configuration bundle

### GET `/management/v1/agents/{agentId}/versions/{versionId}/pull`

Downloads a version's configuration bundle — the current revision, or a
specific one:

<ParamField query="version_tag" type="string">
  Revision tag (e.g. `v3.2`). Omit for the version's current tag.
</ParamField>