Skip to main content
GET
Get Version
{version_id} takes a version number — /versions/3 — as well as a uuid. Prefer the number: it is what every version read gives back, and it needs no lookup first.
The body is the same shape GET /v1/agents/{agent_id} returns, so a version read and an agent read are interchangeable to your code — the difference is only which version you get. The agent read gives you the live one (or the draft, if nothing is live); this gives you the one you name.
Read this before you patch. The document_revision in the response is what PATCH wants in If-Match. Reading, editing and writing back the same revision is what stops your change from silently overwriting someone else’s.
Secrets come back redacted as ‹redacted:5d13bb50e2f1› — a digest of the value, not the value. Send the marker back unchanged and the stored secret is kept; retype it and you replace it.

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.

Response

The agent as this version configures it.

One agent at one version — the response of every agent read, create and update.

A request body is this same object minus the read-only fields, so what you send is what you read back.

id
string
required

The agent's id. Stable across every version.

name
string
required

What the agent is called. Yours to choose; never spoken to a caller.

version
integer
required

Which version this body describes. 0-based, and the identity you use in /versions/{n} and ?version=.

version_id
string
required

This version's uuid. Pass it as agent_version_id on POST /v1/calls to pin a call to this exact version — that field takes a uuid, not a number.

is_published
boolean
required

True once frozen. A published version's configuration can never be edited again; branch a draft instead.

is_live
boolean
required

True if this is the version answering calls right now.

latest_version
integer
required

The highest version number this agent has.

document_revision
integer
required

This version's edit counter. Echo it back as If-Match on your next write and the write becomes a compare-and-set, so you cannot silently overwrite an edit made between your read and your write.

created_at
string<date-time>
required

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

updated_at
string<date-time>
required

When this version was last edited (UTC, ISO 8601).

live_version
integer | null

Which version is live, if any. null means the agent is off air and answers nothing.

label
string | null

Short name for this version, e.g. Shorter greeting. Editable even after publishing — it is metadata, not configuration.

notes
string | null

Longer free text about this version.

blocked_reasons
string[]

Why this version cannot be made live, if it cannot — e.g. it pins a model that has since been retired. Empty means it can go live.

system_prompt
string | null

The agent's instructions. Naming a tool as <tool_name> here is what ARMS it: a tool the prompt never names is never called, and naming one the version does not have is refused on save.

channel_prompts
Channel Prompts · object

Additional instructions appended to the shared system_prompt only in the matching conversation context.

default_instructions
DefaultInstructions · object | null

Ready-made behaviour rules added before system_prompt. See each field. A rule that is missing or null is off.

greeting
Greeting · object | null

What the agent says first.

language
LanguageConfig · object | null

The language it opens in, which others it may switch to, and what triggers a switch.

transcriber
Transcriber · object | null

Speech recognition. GET /v1/transcribers lists valid model values.

model
Model · object | null

The LLM. GET /v1/models lists valid model and provider values.

voice
Voice · object | null

Text to speech. GET /v1/voices lists valid voice_id values, and a voice that cannot speak language.default is refused on save.

conversation
Conversation · object | null

Turn-taking, interruption and noise handling — how it behaves in the back-and-forth.

call
CallSettings · object | null

Limits on the call itself: maximum duration, silence timeout, and what ends it.

inbound
Inbound · object | null

Lines for inbound calls that cannot be handled normally.

builtin_tools
BuiltinTools · object | null

The tools Vocily ships: end the call, hold, transfer, send a WhatsApp template. Each still has to be armed from the prompt.

variables
RuntimeVariable · object[]

The {{placeholders}} the prompt and tools can use. Reference them namespaced as {{custom.your_key}}, never bare.

knowledge_base_ids
string[]

Which knowledge bases this agent can search, from GET /v1/knowledge-bases. This list IS the attachment — there is no separate attach endpoint, and sending it replaces the whole set. An id this workspace does not hold is refused, not ignored.

analysis_group_ids
string[]

Which custom-analysis groups run after each call, from GET /v1/custom-analysis. Same rule as knowledge_base_ids: the list is the attachment, and an id this workspace does not hold is refused, not ignored.

memory
Memory · object | null

Whether the agent remembers callers between calls, and what it is allowed to remember.

numbers
Numbers · object | null

Which phone and WhatsApp numbers this agent answers on. GET /v1/numbers and GET /v1/whatsapp/numbers list what you may use.

dashboard_url
string | null

Deep link to this agent in the Vocily dashboard, for your own UI to link out to.