Versions - AUI

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

cURL

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`

source

string

required

Where the draft starts from: empty, template, or version (clone an existing version).

from_version

string

Required when source is version — the version to clone.

from_template

string

Required when source is template.

label

string

Free-form label for your own bookkeeping.

List versions

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

Lists the agent’s versions as a paginated list, filterable by:

status

string[]

draft, published, archived.

tag

string

Partial match on the version tag (e.g. v3).

version_number

integer

Exact match.

label

string

Partial match on the label.

exclude_revisions

boolean

Only return base versions (revision 0).

Update a version

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

Updates a version’s metadata — label, tags, notes. The configuration itself changes through push, 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:

cURL

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`

caller

string

required

What is pushing: agent_builder, ui, or cli.

commit_message

string

Describe the change (up to 4000 characters).

bundle

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.

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:

version_tag

string

Revision tag (e.g. v3.2). Omit for the version’s current tag.

​Create a draft version

​POST /management/v1/agents/{agentId}/versions

​List versions

​GET /management/v1/agents/{agentId}/versions

​Update a version

​PATCH /management/v1/agents/{agentId}/versions/{versionId}

​Publish a version

​POST /management/v1/agents/{agentId}/versions/{versionId}/publish

​Archive a version

​POST /management/v1/agents/{agentId}/versions/{versionId}/archive

​Push a configuration bundle

​POST /management/v1/agents/{agentId}/versions/{versionId}/push

​Pull a configuration bundle

​GET /management/v1/agents/{agentId}/versions/{versionId}/pull

Create a draft version

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

List versions

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

Update a version

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

Publish a version

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

Archive a version

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

Push a configuration bundle

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

Pull a configuration bundle

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