Get an agent

Get Agent

curl --request GET \
  --url https://api.vocily.ai/v1/agents/{agent_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

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::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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": 1,
  "label": null,
  "notes": null,
  "blocked_reasons": [],
  "created_at": "2026-09-16T19:38:03.767024Z",
  "updated_at": "2026-09-16T19:38:03.767024Z",
  "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,
    "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": ""
    }
  }
}

{
  "detail": "Invalid API key",
  "code": "UNAUTHORIZED"
}

{
  "detail": {
    "code": "validation_error",
    "message": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>",
        "type": "<string>"
      }
    ]
  },
  "code": "VALIDATION_ERROR"
}

{
  "code": "rate_limited"
}

Get Agent

curl --request GET \
  --url https://api.vocily.ai/v1/agents/{agent_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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 => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

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::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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": 1,
  "label": null,
  "notes": null,
  "blocked_reasons": [],
  "created_at": "2026-09-16T19:38:03.767024Z",
  "updated_at": "2026-09-16T19:38:03.767024Z",
  "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,
    "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": ""
    }
  }
}

{
  "detail": "Invalid API key",
  "code": "UNAUTHORIZED"
}

{
  "detail": {
    "code": "validation_error",
    "message": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>",
        "type": "<string>"
      }
    ]
  },
  "code": "VALIDATION_ERROR"
}

{
  "code": "rate_limited"
}

Returns the latest version — what you last wrote — including drafts.

`?version=`	What you get
(omitted)	The newest version, draft or not. What you last wrote
`live`	The version answering real calls. `404` if the agent has never been made live
`3`	That exact version number

Tool secrets come back redacted — an Authorization header reads as ‹redacted:9f2c›. Sending that placeholder back in a later update keeps the stored secret, so reading an agent and writing it straight back is safe.

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.

Query Parameters

version

string | null

live, or a version number like 3. Omit for the latest version.

Response

The agent at the requested version — latest by default.

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

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.

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

Authorizations

Path Parameters

Query Parameters

Response