Update an agent

Patch Agent

curl --request PATCH \
  --url https://api.vocily.ai/v1/agents/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "voice": {
    "speed": 1.2
  }
}
'

import requests

url = "https://api.vocily.ai/v1/agents/{agent_id}"

payload = { "voice": { "speed": 1.2 } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({voice: {speed: 1.2}})
};

fetch('https://api.vocily.ai/v1/agents/{agent_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vocily.ai/v1/agents/{agent_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'voice' => [
        'speed' => 1.2
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vocily.ai/v1/agents/{agent_id}"

	payload := strings.NewReader("{\n  \"voice\": {\n    \"speed\": 1.2\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.vocily.ai/v1/agents/{agent_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"voice\": {\n    \"speed\": 1.2\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vocily.ai/v1/agents/{agent_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"voice\": {\n    \"speed\": 1.2\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "00000005-0000-4000-8000-000000000005",
  "name": "Support line",
  "version": 0,
  "version_id": "00000006-0000-4000-8000-000000000006",
  "is_published": false,
  "is_live": false,
  "live_version": null,
  "latest_version": 0,
  "document_revision": 2,
  "label": null,
  "notes": null,
  "blocked_reasons": [],
  "created_at": "2026-09-16T19:38:03.767024Z",
  "updated_at": "2026-09-16T19:38:03.919698Z",
  "system_prompt": "## Agent Purpose\nYou confirm cash-on-delivery orders for Acme Store.\n\n## Response Style\nWarm, brief, one question at a time.\n\n## Call Flow\n1. Greet {{callee_name}}.\n2. Read back order {{order_id}}.\n3. Ask whether they accept delivery.\n4. Close politely.",
  "greeting": {},
  "language": {
    "default": "hi-IN",
    "additional": [
      "en-IN"
    ],
    "switch_trigger": "requested_or_auto"
  },
  "transcriber": {
    "provider": "sarvam",
    "model": "saaras:v4",
    "keywords": [
      "Acme",
      "COD"
    ],
    "fallback": {
      "provider": "deepgram",
      "model": "nova-3-general"
    }
  },
  "model": {
    "provider": "openai",
    "model": "gpt-5.4-nano",
    "temperature": 0.4,
    "max_tokens": 128,
    "fallback": {
      "provider": "gemini",
      "model": "gemini-3.5-flash-lite"
    }
  },
  "voice": {
    "provider": "vocily",
    "model": "v2",
    "voice_id": "hi-IN-aman",
    "speed": 1.3,
    "emotion": null,
    "fallback": {
      "provider": "sarvam",
      "model": "bulbul:v3",
      "voice_id": "shubh"
    }
  },
  "conversation": {
    "interruption_sensitivity": 0.5,
    "response_eagerness": 0.75,
    "noise_handling": {
      "mode": "standard",
      "level": 50
    },
    "silence_reminder": {
      "enabled": true,
      "seconds": 15
    }
  },
  "call": {
    "max_duration_minutes": 5,
    "end_on_silence_seconds": 25,
    "recording_enabled": true,
    "custom_analysis_enabled": true,
    "max_duration_message": {
      "mode": "default",
      "prompt": "The call has reached its maximum allowed duration and must end now. Generate a brief, natural closing in the same language and tone as the conversation above. The message must clearly preserve this intent: the maximum call time has been reached, so the call is ending now. Keep it to one short sentence, with an optional brief thank-you. Do not ask a question. Do not offer more help, a callback, next steps, or reopen the conversation.",
      "text": ""
    },
    "end_on_silence_message": {
      "mode": "default",
      "prompt": "The caller has been silent for too long and the call is ending now. Generate a brief, natural closing in the same language and tone as the conversation above. The message must clearly preserve this intent: you could not hear anything on the line, so you are ending the call now. Keep it to one short sentence, with an optional brief thank-you. Do not ask a question. Do not offer more help, a callback, next steps, or reopen the conversation.",
      "text": ""
    }
  },
  "builtin_tools": {
    "end_call": {
      "enabled": true
    },
    "hold_call": {
      "enabled": true,
      "max_seconds": 90,
      "follow_up_seconds": 45,
      "acknowledgement_message": {
        "mode": "default",
        "prompt": "Write one short sentence to say to the caller as you start waiting, in the language you have been speaking — confirming you heard them and will wait. Do not ask a question and do not guess why they need the moment.",
        "text": ""
      },
      "follow_up_message": {
        "mode": "default",
        "prompt": "You agreed to wait while the caller stepped away for a moment (they may be fetching a card, a document, or checking something). Generate one very short, gentle check-in in the same language and tone as the conversation above. Keep it to one short sentence, e.g. asking if they are back or reassuring them you are still on the line. Do not say goodbye. Do not say the call is ending. Do not repeat earlier content or ask new questions.",
        "text": ""
      },
      "timeout_message": {
        "mode": "default",
        "prompt": "You agreed to wait while the caller stepped away, but they have not returned and the call is ending now. Generate a brief, natural closing in the same language and tone as the conversation above. The message must clearly preserve this intent: you waited but could not reach them, so you are ending the call; they are welcome to call back. Keep it to one short sentence. Do not ask a question.",
        "text": ""
      }
    },
    "transfer_call": {
      "enabled": true,
      "numbers": [
        {
          "number": "+919876543210",
          "priority": 1,
          "start_hour": 9,
          "end_hour": 20,
          "timezone": "Asia/Kolkata"
        }
      ],
      "busy_message": {
        "mode": "default",
        "prompt": "You tried to transfer the caller to a human teammate, but nobody is available. Generate one short line in the same language and tone as the conversation above, saying the team is busy and someone will call them back on this number. Do not ask a question and do not promise a specific callback time.",
        "text": ""
      },
      "intro_message": {
        "mode": "custom",
        "prompt": "You are about to transfer the caller to a human teammate. Generate one short line in the same language and tone as the conversation above, telling them to hold while you connect them, and that we will call back if the call drops. Do not ask a question and do not promise a specific person or wait time.",
        "text": "Ek minute, main aapko connect karti hoon."
      }
    },
    "send_whatsapp_template": {
      "enabled": false,
      "allowed_templates": [],
      "phone_number_id": ""
    }
  },
  "variables": [
    {
      "key": "callee_name",
      "default_value": null,
      "system_defined": true,
      "deletable": false
    },
    {
      "key": "callee_number",
      "default_value": null,
      "system_defined": true,
      "deletable": false
    }
  ],
  "knowledge_base_ids": [],
  "analysis_group_ids": [
    "00000007-0000-4000-8000-000000000007"
  ],
  "memory": {
    "enabled": true,
    "channels": [
      "outbound",
      "whatsapp"
    ],
    "allow_ai_labels": true,
    "label_instructions": "Record anything about the caller worth knowing next time, even when it is not one of the fields above: who they are, other ways to reach them, how they prefer to be dealt with, their standing with the business, or anything situational. Only what will still be true later; nothing said in passing.",
    "max_facts": 150,
    "transcript_turns": 12,
    "fields": [
      {
        "key": "delivery_pincode",
        "label": "Delivery PIN code",
        "type": "string",
        "enum_values": null,
        "description": "The PIN code the caller wants deliveries sent to.",
        "category": "contact"
      }
    ]
  },
  "numbers": null,
  "dashboard_url": "https://app.vocily.ai/agents/00000005-0000-4000-8000-000000000005",
  "inbound": {
    "business_hours_closed_message": {
      "mode": "default",
      "prompt": "This inbound call arrived outside business hours. Generate one short line telling the caller we are closed right now and inviting them to call back during business hours. Keep it to one sentence. Do not ask a question and do not invent the opening hours.",
      "text": ""
    },
    "fallback_message": {
      "mode": "default",
      "prompt": "This inbound call cannot be handled right now. Generate one short, apologetic line asking the caller to try again later. Keep it to one sentence. Do not ask a question and do not explain the technical reason.",
      "text": ""
    }
  }
}

Patch Agent

curl --request PATCH \
  --url https://api.vocily.ai/v1/agents/{agent_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "voice": {
    "speed": 1.2
  }
}
'

import requests

url = "https://api.vocily.ai/v1/agents/{agent_id}"

payload = { "voice": { "speed": 1.2 } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({voice: {speed: 1.2}})
};

fetch('https://api.vocily.ai/v1/agents/{agent_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vocily.ai/v1/agents/{agent_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'voice' => [
        'speed' => 1.2
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vocily.ai/v1/agents/{agent_id}"

	payload := strings.NewReader("{\n  \"voice\": {\n    \"speed\": 1.2\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.vocily.ai/v1/agents/{agent_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"voice\": {\n    \"speed\": 1.2\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vocily.ai/v1/agents/{agent_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"voice\": {\n    \"speed\": 1.2\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "00000005-0000-4000-8000-000000000005",
  "name": "Support line",
  "version": 0,
  "version_id": "00000006-0000-4000-8000-000000000006",
  "is_published": false,
  "is_live": false,
  "live_version": null,
  "latest_version": 0,
  "document_revision": 2,
  "label": null,
  "notes": null,
  "blocked_reasons": [],
  "created_at": "2026-09-16T19:38:03.767024Z",
  "updated_at": "2026-09-16T19:38:03.919698Z",
  "system_prompt": "## Agent Purpose\nYou confirm cash-on-delivery orders for Acme Store.\n\n## Response Style\nWarm, brief, one question at a time.\n\n## Call Flow\n1. Greet {{callee_name}}.\n2. Read back order {{order_id}}.\n3. Ask whether they accept delivery.\n4. Close politely.",
  "greeting": {},
  "language": {
    "default": "hi-IN",
    "additional": [
      "en-IN"
    ],
    "switch_trigger": "requested_or_auto"
  },
  "transcriber": {
    "provider": "sarvam",
    "model": "saaras:v4",
    "keywords": [
      "Acme",
      "COD"
    ],
    "fallback": {
      "provider": "deepgram",
      "model": "nova-3-general"
    }
  },
  "model": {
    "provider": "openai",
    "model": "gpt-5.4-nano",
    "temperature": 0.4,
    "max_tokens": 128,
    "fallback": {
      "provider": "gemini",
      "model": "gemini-3.5-flash-lite"
    }
  },
  "voice": {
    "provider": "vocily",
    "model": "v2",
    "voice_id": "hi-IN-aman",
    "speed": 1.3,
    "emotion": null,
    "fallback": {
      "provider": "sarvam",
      "model": "bulbul:v3",
      "voice_id": "shubh"
    }
  },
  "conversation": {
    "interruption_sensitivity": 0.5,
    "response_eagerness": 0.75,
    "noise_handling": {
      "mode": "standard",
      "level": 50
    },
    "silence_reminder": {
      "enabled": true,
      "seconds": 15
    }
  },
  "call": {
    "max_duration_minutes": 5,
    "end_on_silence_seconds": 25,
    "recording_enabled": true,
    "custom_analysis_enabled": true,
    "max_duration_message": {
      "mode": "default",
      "prompt": "The call has reached its maximum allowed duration and must end now. Generate a brief, natural closing in the same language and tone as the conversation above. The message must clearly preserve this intent: the maximum call time has been reached, so the call is ending now. Keep it to one short sentence, with an optional brief thank-you. Do not ask a question. Do not offer more help, a callback, next steps, or reopen the conversation.",
      "text": ""
    },
    "end_on_silence_message": {
      "mode": "default",
      "prompt": "The caller has been silent for too long and the call is ending now. Generate a brief, natural closing in the same language and tone as the conversation above. The message must clearly preserve this intent: you could not hear anything on the line, so you are ending the call now. Keep it to one short sentence, with an optional brief thank-you. Do not ask a question. Do not offer more help, a callback, next steps, or reopen the conversation.",
      "text": ""
    }
  },
  "builtin_tools": {
    "end_call": {
      "enabled": true
    },
    "hold_call": {
      "enabled": true,
      "max_seconds": 90,
      "follow_up_seconds": 45,
      "acknowledgement_message": {
        "mode": "default",
        "prompt": "Write one short sentence to say to the caller as you start waiting, in the language you have been speaking — confirming you heard them and will wait. Do not ask a question and do not guess why they need the moment.",
        "text": ""
      },
      "follow_up_message": {
        "mode": "default",
        "prompt": "You agreed to wait while the caller stepped away for a moment (they may be fetching a card, a document, or checking something). Generate one very short, gentle check-in in the same language and tone as the conversation above. Keep it to one short sentence, e.g. asking if they are back or reassuring them you are still on the line. Do not say goodbye. Do not say the call is ending. Do not repeat earlier content or ask new questions.",
        "text": ""
      },
      "timeout_message": {
        "mode": "default",
        "prompt": "You agreed to wait while the caller stepped away, but they have not returned and the call is ending now. Generate a brief, natural closing in the same language and tone as the conversation above. The message must clearly preserve this intent: you waited but could not reach them, so you are ending the call; they are welcome to call back. Keep it to one short sentence. Do not ask a question.",
        "text": ""
      }
    },
    "transfer_call": {
      "enabled": true,
      "numbers": [
        {
          "number": "+919876543210",
          "priority": 1,
          "start_hour": 9,
          "end_hour": 20,
          "timezone": "Asia/Kolkata"
        }
      ],
      "busy_message": {
        "mode": "default",
        "prompt": "You tried to transfer the caller to a human teammate, but nobody is available. Generate one short line in the same language and tone as the conversation above, saying the team is busy and someone will call them back on this number. Do not ask a question and do not promise a specific callback time.",
        "text": ""
      },
      "intro_message": {
        "mode": "custom",
        "prompt": "You are about to transfer the caller to a human teammate. Generate one short line in the same language and tone as the conversation above, telling them to hold while you connect them, and that we will call back if the call drops. Do not ask a question and do not promise a specific person or wait time.",
        "text": "Ek minute, main aapko connect karti hoon."
      }
    },
    "send_whatsapp_template": {
      "enabled": false,
      "allowed_templates": [],
      "phone_number_id": ""
    }
  },
  "variables": [
    {
      "key": "callee_name",
      "default_value": null,
      "system_defined": true,
      "deletable": false
    },
    {
      "key": "callee_number",
      "default_value": null,
      "system_defined": true,
      "deletable": false
    }
  ],
  "knowledge_base_ids": [],
  "analysis_group_ids": [
    "00000007-0000-4000-8000-000000000007"
  ],
  "memory": {
    "enabled": true,
    "channels": [
      "outbound",
      "whatsapp"
    ],
    "allow_ai_labels": true,
    "label_instructions": "Record anything about the caller worth knowing next time, even when it is not one of the fields above: who they are, other ways to reach them, how they prefer to be dealt with, their standing with the business, or anything situational. Only what will still be true later; nothing said in passing.",
    "max_facts": 150,
    "transcript_turns": 12,
    "fields": [
      {
        "key": "delivery_pincode",
        "label": "Delivery PIN code",
        "type": "string",
        "enum_values": null,
        "description": "The PIN code the caller wants deliveries sent to.",
        "category": "contact"
      }
    ]
  },
  "numbers": null,
  "dashboard_url": "https://app.vocily.ai/agents/00000005-0000-4000-8000-000000000005",
  "inbound": {
    "business_hours_closed_message": {
      "mode": "default",
      "prompt": "This inbound call arrived outside business hours. Generate one short line telling the caller we are closed right now and inviting them to call back during business hours. Keep it to one sentence. Do not ask a question and do not invent the opening hours.",
      "text": ""
    },
    "fallback_message": {
      "mode": "default",
      "prompt": "This inbound call cannot be handled right now. Generate one short, apologetic line asking the caller to try again later. Keep it to one sentence. Do not ask a question and do not explain the technical reason.",
      "text": ""
    }
  }
}

Send only what you want to change.

{ "voice": { "speed": 1.2 },
  "conversation": { "noise_handling": { "mode": "high" } } }


Objects	Merge. Sending `voice.speed` leaves `voice.voice_id` alone
Lists	Replace whole. Sending one entry in `variables` removes the others
`null`	Clears the field

Giving the transcriber, model or voice a backup provider? See Backups - each one takes a slightly different shape.

Choosing the version

?version=3 changes that version — the mirror of GET /v1/agents/{id}?version=3, so reading and writing take the same selector.

PATCH /v1/agents/{agent_id}?version=3

A published version’s configuration is refused with 409 version_immutable, whether you name it by number or as live: it is frozen, which is what makes a rollback exact.

Renaming a version

label and notes go in the same body. They name the version the change lands on, and they are not configuration, so they apply to any version - a published one included:

PATCH /v1/agents/{agent_id}?version=3

{ "label": "Holiday hours", "notes": "Closes at 4pm on public holidays." }

Send them alongside configuration to change and name a draft in one request. Omit it and the change goes to your working draft — see below.

Where the change lands

On the agent’s working draft — and which one that is has to be unambiguous, because we will not guess on your behalf:

Drafts open	What happens
None — the newest version is published, the normal state of a live agent	A new draft is branched from the live version and returned to you
Exactly one	It is edited
Two or more	`409 multiple_drafts`, listing each one. Name the one you mean

Nothing you change here reaches a caller until you publish that draft and make it live.

An agent may hold as many drafts as you like, and your colleagues create them from the dashboard too. If more than one is open we refuse rather than pick — writing your change into somebody else’s unreviewed draft would succeed silently, and you would have no way to tell.

{ "code": "multiple_drafts",
  "message": "This agent has more than one unpublished draft…",
  "drafts": [ { "version": 2, "label": "Transfer hours" },
              { "version": 1, "label": "New greeting" } ] }

The error carries the labels, so you can choose without a second call. Then name it:

PATCH /v1/agents/{agent_id}?version=1

That form never guesses — use it whenever you know which draft you want.

Editing safely from two places

Send If-Match with the document_revision you read, and a write composed against a stale copy is refused with 409 version_document_stale rather than overwriting someone else’s change.

PATCH /v1/agents/bc17a739-…
If-Match: "4"

Leave it out and your change applies to whatever the draft holds now — usually what you want for a script changing one field.

Authorizations

Authorization

string

header

required

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

Headers

If-Match

string | null

The document_revision this change was composed against. Omit to write against whatever the draft holds now.

Path Parameters

agent_id

string

required

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

Query Parameters

version

string | null

Which version to change, by number — e.g. 3. Omit to change the agent's working draft. A published version is refused: its configuration is frozen.

Body

application/json

Change any setting. Merge-patch: objects merge, lists replace whole, null clears.

Applies to the agent's newest draft. If the newest version is published, a draft is branched from the live version first — a published version's configuration cannot change.

name

string | null

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

Required string length: 1 - 255

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.

Required string length: 1 - 65536

greeting

Greeting · object | null

What the agent says first.

Show child attributes

language

LanguageConfig · object | null

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

Show child attributes

transcriber

Transcriber · object | null

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

Show child attributes

model

Model · object | null

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

Show child attributes

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.

Show child attributes

conversation

Conversation · object | null

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

Show child attributes

call

CallSettings · object | null

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

Show child attributes

inbound

Inbound · object | null

Lines for inbound calls that cannot be handled normally.

Show child attributes

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.

Show child attributes

variables

RuntimeVariable · object[] | null

The {{placeholders}} the prompt and tools can use. Reference them namespaced as {{custom.your_key}}, never bare. Sending this list replaces the whole set.

Show child attributes

knowledge_base_ids

string[] | null

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[] | null

Which custom-analysis groups run after each call, from GET /v1/custom-analysis. 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.

Show child attributes

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.

Show child attributes

label

string | null

Short name for the version this change lands on. Editable on a published version too.

Maximum string length: 80

notes

string | null

Longer free text for the version this change lands on. Editable on a published version too.

Response

The version the change landed on, after it — the working draft, or the one ?version= named.

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.

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.

greeting

Greeting · object | null

What the agent says first.

Show child attributes

language

LanguageConfig · object | null

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

Show child attributes

transcriber

Transcriber · object | null

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

Show child attributes

model

Model · object | null

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

Show child attributes

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.

Show child attributes

conversation

Conversation · object | null

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

Show child attributes

call

CallSettings · object | null

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

Show child attributes

inbound

Inbound · object | null

Lines for inbound calls that cannot be handled normally.

Show child attributes

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.

Show child attributes

variables

RuntimeVariable · object[]

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

Show child attributes

knowledge_base_ids

string[]

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.

Show child attributes

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.

Show child attributes

dashboard_url

string | null

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

Calls

Chats

Phone Numbers

Knowledge Bases

Agents

Catalogues

Integrations

Custom Analysis

Memory

Widget

Webhooks

Update an agent

Choosing the version

Renaming a version

Where the change lands

Editing safely from two places

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

​Choosing the version

​Renaming a version

​Where the change lands

​Editing safely from two places

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

Choosing the version

Renaming a version

Where the change lands

Editing safely from two places