--- title: "Read one agent" method: GET path: "/v1/agents/{id}" --- # Read one agent `GET /v1/agents/{id}` ## Request - Base URL: `https://volai.cz` - URL: `https://volai.cz/v1/agents/{id}` - Auth: HTTP bearer The detail of a single agent. A deleted agent returns 404 `agent_not_found`. At creation, `useForOutboundTasks` selects the initial platform: `true` chooses volai's engine, `false` ElevenLabs, and omission uses the deployment default. Since `POST` returns only an `id`, verify the result in this follow-up `GET` and its `provider` field. Enabling `transferTo` on an ElevenLabs agent triggers an engine switch attempt, but it may be paused, unavailable or fail; handoff does not work while `provider` remains `elevenlabs`. A successful switch may change the voice. Changing `language` with `PATCH` from a language in which new agents start on ElevenLabs (today `en`, `de`, `pl`) to one in which they start on the engine (`cs`, `sk`) triggers the same attempt: on success the agent gets the new language's default engine voice (Milena, Katarina), on failure it stays on ElevenLabs. A change between `cs` and `sk` moves nothing. Other provider moves are handled by support. ElevenLabs accepts only `anet` from the catalog or a raw ElevenLabs voice id; other catalog voices require the engine. The response also always carries a `laughterEffective` field (`{active, reason, sensitiveCategory} | null`) - the live laughter-policy outcome for the agent's PUBLISHED configuration, computed fresh outside of any call. For an ElevenLabs agent it's always `{active: false, reason: "not_engine", sensitiveCategory: null}` without calling the engine; for an engine agent `reason` is one of several values (`ok`, `agent_off`, `sensitive_prompt`, `voice_not_listed` and more) and the engine may add new ones over time - treat an unknown value as off, not as an error. When the engine doesn't answer within 3 seconds, is down, or doesn't know the agent (a silent 404 on an older build), `laughterEffective` is `null` outright - never a guess. ## Path parameters - `id` string, required ## Response `200` Agent - object - `agent` object, required - `id` string, required - `name` string, required - `language` string, required - `systemPrompt` string, required - `firstMessage` string - `voiceId` string - `provider` 'elevenlabs' | 'engine', required - `numberE164` string - `createdAt` number, required - `status` 'active' | 'deleted', required - `toolIds` string[] - `transferTo` string - `transferCondition` string - `dataFields` object[] - `key` string, required - `type` 'string' | 'number' | 'boolean', required - `description` string, required - `enumValues` string[] - `recordCalls` boolean - `goal` string, nullable, required - `knowledge` string, nullable, required - `notifyEmail` boolean, required - `voicemail` object - `enabled` boolean, required - `action` 'mark' | 'hangup' | 'message', required - `message` string - `silencePromptSecs` integer, nullable, required - `laughter` 'auto' | 'on' | 'off', required - `firstMessageProtectSecs` number, nullable, required: Seconds of the first line protected from short reactions by the person who answered (outbound calls on the volai engine), 0 to 20. A reply without an interrupting word (for example stop, no, wait) is dropped in that window: it does not interrupt the line, is not in the transcript and the agent does not react to it; an interrupting word still interrupts it. The interrupting words follow the agent's language: an English agent is interrupted by stop, no, wait or hold. null means not set, so the engine plays the first line as before. - `silencePromptText` string, nullable, required: Your own sentence for the silence reminder, spoken word for word instead of the default reminder for the agent's language. null means the default text is used. Heard only once the agent runs on the volai engine. - `sttLanguageHintsStrict` boolean, required: Strict language lock for speech recognition on the volai engine (Soniox language_hints_strict): the transcript strongly prefers the agent's language, so a short reply is not written as a foreign word or in another script. Best effort; meant for cs agents with outbound calls, never for sk. false when not set. Read only by the engine, ElevenLabs ignores it. - `turnDigitTailFloorMs` integer, nullable, required: Silence floor in milliseconds the volai engine keeps after a reply that ends with a group of 3 to 8 digits (a caller dictating a number), 0 (off) or 400 to 2300; the recommended first step for Czech agents that take dictated numbers is 800. null means not set, so the engine default (0, off) applies. Used only by the engine. - `turnLongSpeechFloorMs` integer, nullable, required: Silence floor in milliseconds the volai engine keeps after the caller spoke for longer than turnLongSpeechSecs, 0 (off) or 400 to 2300. null means not set, so the engine default (0, off) applies. Used only by the engine. - `turnLongSpeechSecs` number, nullable, required: Speech length in seconds above which turnLongSpeechFloorMs applies, 1 to 30. null means not set, so the engine default (5) applies. Has no effect while turnLongSpeechFloorMs is off. - `inboundVariables` object: Default values for {{variable}} placeholders on inbound calls, merged into the call's dynamic variables only for names the inbound call does not supply itself (caller_number, called_number, attempt_id, volai_*, trial_*, system__*). Absent when the agent has none. Not used on outbound calls. Works for either provider. - `workflow` object: Call split into phases (nodes). Absent means the agent runs as a single phase, as before. See the "Call phases (workflow)" section for the full shape, limits and an example. - `version` 1, required: Workflow format version, currently always 1. - `entry` string, required: Id of the node the call starts in. Must exist among nodes. - `nodes` object[], required: Call phases, 2 to 8 nodes. - `id` string, required: Machine id of this node: lowercase letters, digits and underscores, starting with a letter, up to 32 characters. Must be unique within the workflow. The words start, start_node, end and end_node are reserved. - `label` string, required: Human-readable phase name, 1 to 60 characters. - `prompt` string: Prompt addition that only applies while the call is in this node, up to 2000 characters. The agent's base systemPrompt should only hold what is true in every phase. - `knowledge` string: Extra knowledge that only applies in this node, up to 4000 characters. prompt and knowledge combined must not exceed 4000 characters for one node. - `toolIds` string[]: Ids of account tools (from list_tools) visible only while the call is in this node, at most 10. A tool not assigned to any node stays visible in every node. - `enterPhrase` string: Sentence spoken immediately on entering this node, at most once per call, up to 160 characters. - `enterBehavior` 'reply' | 'wait': Defaults to "reply". "wait" means the model does not answer in the same turn after speaking enterPhrase and waits for the caller instead; requires enterPhrase. - `edges` object[], required: Transitions between phases, 1 to 24 edges, at most 5 leaving any one node. - `id` string, required: Machine id of this edge: lowercase letters, digits and underscores, starting with a letter, up to 48 characters. Must be unique within the workflow. - `from` string, required: Id of the node this edge leaves. - `to` string, required: Id of the node this edge enters. Must differ from from. - `condition` string, required: When to take this edge, written about what the CALLER said (never about what the agent or a tool did), 5 to 200 characters. Goes verbatim into the description of the switch_to_{to} tool. - `calendar` object: Calendar availability rules for check_availability/book_appointment on volai's own voice engine. Absent means the agent does not book appointments. Effective only once provider is engine - see calendar_pending_engine_switch in warnings. - `integrationId` string, required: Id of the connected calendar integration this agent books through, from list_integrations. - `calendarId` string, required: Id of the specific calendar within that connection, from list_calendars. The agent writes appointments into this calendar, so it must be writable (accessRole owner or writer); a read-only calendar is rejected with calendar_invalid_calendar. - `busyCalendarIds` string[]: Other calendars in the same connection whose events also block a slot; nothing is written into them, so read-only calendars are fine. At most 4, without duplicates and without calendarId. - `timezone` string, required: IANA timezone the windows and spoken times are interpreted in, for example Europe/Prague. - `slotMinutes` union, required: Length of each offered appointment slot in minutes. - 15 - 30 - 45 - 60 - 90 - 120 - `minNoticeMinutes` number, required: Minimum notice before the earliest offered slot, in minutes. - `horizonDays` number, required: How many days ahead the agent searches for a free slot. - `bufferMinutes` number, required: Buffer kept free immediately before and after every busy event, in minutes. - `windows` object, required: Availability windows for every weekday. At least one weekday needs a non-empty window. - `mon` object[], required: Availability windows on Monday. An empty array means no availability that day. - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone. - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone. - `tue` object[], required: Availability windows on Tuesday. An empty array means no availability that day. - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone. - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone. - `wed` object[], required: Availability windows on Wednesday. An empty array means no availability that day. - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone. - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone. - `thu` object[], required: Availability windows on Thursday. An empty array means no availability that day. - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone. - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone. - `fri` object[], required: Availability windows on Friday. An empty array means no availability that day. - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone. - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone. - `sat` object[], required: Availability windows on Saturday. An empty array means no availability that day. - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone. - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone. - `sun` object[], required: Availability windows on Sunday. An empty array means no availability that day. - `from` string, required: Start of this window as local time HH:MM in the agent's calendar timezone. - `to` string, required: End of this window as local time HH:MM in the agent's calendar timezone. - `missedCallSms` object, required: Send an SMS to the caller when this agent misses the call (unanswered outbound, missed inbound). enabled: false when off. text is a custom template (up to 320 characters); absent uses the default text in the agent's language. - `enabled` boolean, required - `text` string - `suspended` boolean, required: Whether the volai operator has manually suspended this agent. A suspended agent can't receive or make calls or send missed-call SMS; its settings stay editable. A suspension of the whole account is reported as the `account_suspended` error on every request instead. - `laughterEffective` object, nullable, required: Laugh policy outcome for the currently published configuration, computed fresh outside of any call. null means the state could not be determined right now (for example the engine did not respond) - never a guess. - `active` boolean, required - `reason` string, required: Why the effective state is what it is. Known values: disabled, deny_invalid, no_agent_id, agent_denied, agent_not_listed, setting_absent, agent_off, voice_not_listed, language, provider, language_text, prompt_unrendered, sensitive_prompt, ok, ok_forced, not_engine. The engine may add further values; treat any unlisted one as "not laughing right now". - `sensitiveCategory` string, nullable, required ## Other responses - `401`: Error codes: unauthorized (request). - `403`: Error codes: account_suspended (account). - `404`: Error codes: agent_not_found (account). - `429`: Error codes: rate_limited (busy). - `500`: Error codes: internal_error (service). --- [API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)