Skip to main content
Publish Version
Publishing does not put the version in front of callers. It freezes the configuration so it can never change again, which is what makes a later rollback mean something exact. Make it live is the step callers feel.
Both optional — V4 is already the version’s identity, so a label is description rather than a name.

Publishing and deploying in one call

Freezes the version and puts it live, in one request. Never implicit: leave the flag out and you get the two-step behaviour above. It exists because a script deploying twenty agents should not need forty calls. After this, the version’s configuration is immutable. Editing it returns 409 version_immutable; updating the agent branches a fresh draft instead. Only label and notes can still be changed.

Authorizations

Authorization
string
header
required

Your API key as a Bearer token, e.g. Authorization: Bearer vk_….

Path Parameters

agent_id
string
required

The agent's id, as GET /v1/agents returns it.

version_id
string
required

A version number (0, 1, 3) or a version uuid — both resolve. Prefer the number: it is the version's identity to you, it is what every version read returns, and it needs no lookup first.

Body

application/json

Freeze a draft. make_live deploys it in the same call.

V<n> is already the version's identity, so label is description rather than identification and forcing one only buys junk names.

label
string | null

Short name to freeze onto this version.

Maximum string length: 80
notes
string | null

Longer free text to freeze onto it.

make_live
boolean
default:false

Publish AND put it on air in one call. Read the result back as is_live.

Response

The frozen version. Publishing does NOT deploy unless you sent make_live: true.

One version in an agent's history.

Versions are identified by NUMBER: it is what every version read returns and what ?version= and /versions/{n} take.

version
integer
required

This version's number — what you pass in /versions/{n}.

version_id
string
required

This version's uuid. Published because POST /v1/calls pins a call with agent_version_id, which takes a uuid rather than a number.

is_published
boolean
required

True once frozen. Configuration can never be edited again; label and notes still can.

is_live
boolean
required

True if this is the version answering calls right now.

document_revision
integer
required

This version's edit counter. Send it as If-Match to make a write conditional.

created_at
string<date-time>
required

When this version was created (UTC, ISO 8601).

label
string | null

Short name for this version.

notes
string | null

Longer free text about this version.

base_version
integer | null

Which version this one was branched from, by NUMBER — null for the agent's first.

blocked_reasons
string[]

Why this version cannot be made live, if it cannot — e.g. it pins a retired model. Check it before offering a deploy button, so the button never fails on click.

inbound_phone
string | null

The phone number this version will answer on once it is made live. Inert until then.

inbound_whatsapp
string | null

The WhatsApp number this version will answer on once it is made live. Inert until then.

published_at
string<date-time> | null

When it was frozen. null while it is still a draft.