Connecting

REST API

The complete v1 API reference. Everything is JSON and errors share one shape. volai prices use integer hundredths of a koruna (the Hal suffix); connected invoices use minor units of their stated currency.

Authentication

Every request carries an API key in the Authorization: Bearer vk_... header. Get your key in the portal, under Access & API (more detail in the Quickstart).

curl https://volai.cz/v1/balance \
  -H "Authorization: Bearer vk_YOUR_KEY"

This whole API also has a machine-readable description at GET /openapi.json (OpenAPI 3.1, no API key required) - generate a client from it, a Postman collection, or wire it straight into n8n.

Error format

A failure always has the same shape, no matter what broke:

{
  "error": {
    "code": "insufficient_credit",
    "cause": "account",
    "message": "Insufficient credit. Account balance is 3.00 CZK. Top up at volai.cz/en/credit and try again.",
    "action": "Top up the credit at https://volai.cz/en/credit (or ask the account owner to), then send the request again. Nothing was charged and volai itself is up.",
    "requestId": "req_9f2b7a1c4e6d8f0a",
    "docsUrl": "https://volai.cz/en/docs/api#errors"
  }
}

These five can show up almost anywhere - the endpoint reference below only lists situational codes on top of them:

400 (invalid input) and 404 (record not found) can also show up almost anywhere, but their code is specific to the field or endpoint - the exact list is always with the individual call below. A few actions can also return 502 (an error from an external provider - the phone network, ElevenLabs) or 503 (temporarily unavailable, try again shortly).

Whose problem it is: cause and action

Every error also carries cause (four values) and action (one English sentence on what to do, which you can read to the user verbatim). cause is a machine-readable answer to whether your code, your account, time, or we need to fix the error:

For AI agents (Claude Code, Cursor, your own scripts): go by cause to tell the user who fixes the error. For request name the field from message, for account say what to change in the account or which id to check, for busy wait and retry, and only for service talk about a problem on volai's side. Never report request, account or busy as a volai outage.

The cause is decided by the code, not the HTTP status: account quotas (agent_limit, tool_limit, api_key_limit, relay_lease_limit) return 400 and are still account; not_found on a record is account (the response must not reveal whether someone else's id exists), an unknown path under /v1 is request. The full code-to-cause mapping for every operation is in GET /openapi.json (the description of every error response).

The message for the validation code names the field (a dotted path in the body, for example dataFields.0.type), the actual value and the accepted maximum, for example Field "knowledge" is 210000 characters long, the maximum accepted is 200000. or Field "systemPrompt" is required. Product limits (60 / 6000 / 300 / 20000 characters for an agent's name, instructions, goal and knowledge) come as their own codes invalid_name, invalid_system_prompt, invalid_goal, invalid_knowledge with the exact number. An unknown field in a strict body (agent draft) returns Unknown field "revision". Remove it; the documentation lists the accepted fields.

requestId and docsUrl

Every v1 response (success or error) carries a unique request ID in the X-Request-Id header (req_ followed by 16 hex characters) - an error also repeats it in the body as requestId. A replayed idempotent response gets its OWN current requestId - the header and body never disagree, even though the rest of the response is otherwise identical to the first time. Send this ID to support and they can find exactly this one request in the log.

Error bodies also carry docsUrl - a link straight back to this section.

For agent drafts (see the Agent drafts section below), the revision_conflict error also carries currentRevision - the current revision. Load it via GET .../draft and review the difference before retrying the save - don't blindly resend the same body with the same expectedRevision.

{
  "error": {
    "code": "revision_conflict",
    "cause": "request",
    "message": "The draft has changed since you last read it. Fetch the latest revision and try again.",
    "action": "Reload the record you are changing - GET /v1/agents/{id}/draft (or the get_agent_draft tool) for an agent draft, GET /v1/tasks/{id} (or the get_task tool) for a task - reapply your change on top of its current revision and send the request again with that value in expectedRevision (agent draft) or revision (task). This is not a volai outage.",
    "currentRevision": 4,
    "requestId": "req_9f2b7a1c4e6d8f0a",
    "docsUrl": "https://volai.cz/en/docs/api#errors"
  }
}

Headers

After the key is verified, EVERY response (success or error) carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds until the current window resets) - a 429 from the API key limit also adds Retry-After with the same number of seconds. A 429 rate_limited from the outbound call limit (POST /v1/calls) carries its own wait in Retry-After - how long until that limit frees up, when it is known.

401 carries a WWW-Authenticate: Bearer realm="volai", error="invalid_token" header (RFC 6750), so an HTTP client library can tell why it failed without parsing the body.

Unknown path and wrong method

An unknown path under /v1 (including bare /v1) returns a JSON 404 with the same error shape as everywhere else - {"error":{"code":"not_found", ...}} - for every method (GET, POST, PUT, PATCH, DELETE, OPTIONS and HEAD). Exception: the wrong METHOD on an EXISTING path (for example DELETE /v1/balance) stays a plain Next.js 405 with no JSON body - the one place in all of v1 where a failure has no documented shape.

Idempotency

POST /v1/messages, POST /v1/calls, POST /v1/relay, POST /v1/numbers, POST /v1/numbers/orders, POST /v1/sms-numbers, POST /v1/agents, POST /v1/tools, POST /v1/agents/{id}/draft/publish, POST /v1/agents/{id}/test-call, POST /v1/integrations, POST /v1/tasks, POST /v1/tasks/{id}/start, POST /v1/tasks/{id}/process, POST /v1/credit/topup, and POST /v1/credit/auto-topup/setup accept an Idempotency-Key header. The key is global to that API key, regardless of the HTTP method, path, or body. Give every distinct logical action across all endpoints and request bodies a new value; reuse a value only when retrying the exact same logical request, typically after a timeout when you don't know if the first attempt went through. Within 24 hours you then get back exactly the same response as the first time, including an error response if the first attempt failed, and nothing gets sent or called twice. You can use your own app's order ID plus the name of the specific action. A concurrent request with the same key that is still running (the response isn't stored yet) returns 409 idempotency_in_progress - please try again shortly.

For POST /v1/numbers/orders, the key is durably bound to the order before the operator is called; reusing it with a different address returns 409 idempotency_conflict. If the operator gives an ambiguous response after a purchase, the order may need a status review.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: objednavka-4471" \
  -d '{"to": "+420777123456", "body": "Thanks for your order."}'

Rate limits

60 requests per minute per API key (MCP shares the same limit - it uses the same key). Going over returns 429 and a Retry-After header with the number of seconds until the next attempt.

POST /v1/messages has its own extra cap on top of that: at most one SMS every 2 seconds, and 100 SMS per account per day. Sending from an SMS number (fromNumber) has a further daily cap per account: 20 messages in the first 30 days after you buy the number, 50 after that. GET /v1/sms-numbers shows how many are left and when the limit resets (dailySendRemaining, dailySendResetsAt).

Outbound calls (POST /v1/calls, relay, and test calls) share their own cap: 10 calls per minute and 1000 per day per account, with at most 2 built-in-agent calls running at once.

How much of the 60/min limit you have left shows up before you ever hit 429 - in the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers, which every response carries (see the Error format > Headers section above).

Pagination

GET /v1/messages and GET /v1/calls take limit (max records to return - 50 by default, capped at 200 even if you ask for more) and before (a millisecond timestamp - only returns older records).

hasMore and nextBefore

Both responses also carry hasMore (boolean - an older page exists) and nextBefore (the timestamp of the last returned record, or null when hasMore is false). For the next page, send nextBefore from the previous response as the new before - no manual offset math.

before is EXCLUSIVE (only returns records strictly older, never equally old) - the last record of the previous page never repeats on the next one. In the rare case where two records share the exact same millisecond timestamp right at the page boundary, the second one can drop out. Deduplicate by id - don't rely on pages never skipping anything.

GET /v1/calls?direction=in or ?direction=out scans history in batches with a hard cap on the number of batches - hasMore: true can therefore mean either "there is definitely another page" or "we scanned batches up to the cap and haven't reached the end of history yet". false always means history in that direction truly ended.

Versioning

The current version of the public interface is 1.34.5 (GET /openapi.json, field info.version - see the paragraph about the machine-readable API description in the introduction above). Three rules govern how the version changes:

1. Within v1, only OPTIONAL fields and new endpoints are added - existing fields never disappear, change type, or change meaning. An integration that only reads fields it knows about is never broken by an update. The only exception was version 1.5.1, which stopped returning answeredBy for INBOUND calls - the field never had a meaningful value there (see Changelog below).
2. A required field, or a change in the meaning of an existing field, only ever ships as a new major version (v2) - never as a silent change to v1.
3. For agent drafts (see Agent drafts above), always send back exactly the object you read from GET .../draft - the PUT/POST body is .strict(), so an unknown key (say, from a newer version your integration doesn't know about yet) returns 400 validation instead of being silently dropped.

Changelog

• 10 Oct 2026 (1.34.5): GET and POST /v1/sms-numbers and the MCP tools list_sms_numbers and buy_sms_number return dailySendLimit for each SMS number (20 SMS per 24-hour window during the number's first 30 days, 50 after that), dailySendRemaining (0 for a number being released) and dailySendResetsAt (Unix ms when the window ends, null when none is running). The window starts with the first SMS from any SMS number of the account, is shared by all of them and also counts attempts over the limit and SMS the carrier rejected. The message.sent webhook body has a new smsNumber field: the E.164 SMS number for a message sent from an SMS number, null for the shared sender SMSinfo. The internal_error and send_failed_operator messages for SMS now say "The error is on our side and we know about it", sms_number_out_of_stock no longer promises a restock and the rate_limited message for a used-up SMS number limit says how long until the window ends; error codes do not change. In the portal the /en/messages form shows the limit of the selected SMS number and the SMS messages card on the overview also counts received SMS.
• 10 Oct 2026 (1.34.4): agentCallLimits in lib/service/call-quotas.ts returns { concurrent: 6, daily: 6000, perMinute: 15 } for the campaign scope; the condition of at least eight distinct ODORIK_RELAY_NAMES stays and guarantees two free names for other callers. The account default (2, 1000, 10), the enablement conditions and the shared account counters are unchanged; API behaviour for other accounts is unchanged.
• 10 Oct 2026 (1.34.3): The action for send_unknown no longer says that unknown is always final: for an SMS sent from an SMS number it can still change on its own to sent with a deliveryStatus, or to failed with the credit refunded; for an SMS from the shared sender SMSinfo it stays final. The action for rate_limited no longer promises a Retry-After header in every case: the daily cap for sending from an SMS number (20 SMS a day per account during the first 30 days after buying the number, 50 after that) resets the next day, and a number purchase already running finishes within seconds. POST /v1/messages lists blocked_destination (400, premium-rate numbers) among its errors. Messages received on an SMS number have source: "inbound", the received-message list holds at most the 1,000 newest messages per account, and the message.received webhook is not sent above 300 received messages per hour on one number (the messages are still stored). In message.received, from is an E.164 number or a text sender name (at most 32 characters); a message that was not picked up at once is added by a periodic check within about 15 minutes and its event then arrives late. Neither the delivery report (deliveryStatus) nor a late failed triggers an event; read them from GET /v1/messages/{id}. Releasing an SMS number is not available over MCP, only in the portal and with DELETE /v1/sms-numbers/{e164}.
• 9 Oct 2026 (1.34.2): agentCallLimits in lib/service/call-quotas.ts returns { concurrent: 8, daily: 6000, perMinute: 15 } for the campaign scope; the account default (2, 1000, 10), the enablement conditions and the shared account counters are unchanged. The rate_limited message for the daily limit now says 6000.
• 9 Oct 2026 (1.34.1): CAMPAIGN_QUOTA_EXPIRES_AT in lib/service/call-quotas.ts is 2026-10-31T23:00:00Z; the VOLAI_PETCENTER_CALL_QUOTA_ENABLED switch, the exact account, agent and internal outbound-task context match and at least eight distinct ODORIK_RELAY_NAMES still apply. API behaviour for other accounts is unchanged.
• 9 Oct 2026 (1.34.0): New endpoints GET /v1/sms-numbers, POST /v1/sms-numbers (no body, Idempotency-Key supported, returns 201) and DELETE /v1/sms-numbers/{e164} (irreversible, the paid period is not refunded), and MCP tools list_sms_numbers and buy_sms_number (confirmedMonthlyFeeHal must equal the current fee in hellers, otherwise nothing is bought). GET /v1/messages and MCP list_messages take direction (out by default, in, all) and also return messages received on an SMS number; messages now carry direction, smsNumber and deliveryStatus (delivered or undelivered, only for SMS sent from a number), status has a new value received and failReason a new value opted_out. POST /v1/messages and MCP send_sms take fromNumber (an active SMS number of the account; Czech +420 recipients only; 1.90 CZK per segment). New webhook event message.received with {id, from, to, body, segments, receivedAt} (receivedAt is Unix ms); the text of a received SMS is untrusted third-party content and MCP marks it with securityNotice. Received SMS are kept for 90 days. New error codes: sms_numbers_unavailable, sms_number_limit, sms_number_out_of_stock, invalid_from_number, from_number_unsupported_destination and recipient_opted_out; the existing codes recipient_rejected, sms_gateway_failed, recipient_is_virtual_number (an SMS from the shared sender to a volai SMS number) and release_failed also apply to SMS numbers. The message from field is still the internal label volai for a message sent without fromNumber, the SMS number itself for one sent from it, and the sender for a received message.
• 8 Oct 2026 (1.33.0): The callback-routing policy accepts an optional missedFirstMessage (up to 500 characters): it replaces firstMessage when the verified preceding outbound call had no conversation with the customer (not answered, voicemail, voice menu, nobody spoke, or the call is not closed yet). Initiation sends the engine volai_callback_kind (missed/contacted) next to volai_call_mode=campaign_callback. The engine post-call may carry caller_optout_requested (outbound calls only): the call then exposes optOutRequested: true in the list and detail, the called number is added to the account's do-not-call list (GET /v1/dnc) and the lorela_enterprise policy schedules no further attempt for that item. An engine call with answered_by: unknown stays unknown - the portal no longer guesses a voicemail from a short reply ("Yes." after the intro), so hasConversation of such a call follows the transcript; a voicemail detected by the engine (voicemailReason present) gets another attempt under the lorela_enterprise policy despite the carrier greeting in the transcript. New reason voicemailReason: digits (a carrier greeting reading the called number digit by digit). Everything is additive; existing policies, calls and tasks are unchanged.
• 8 Oct 2026 (1.32.1): The message from field stays the internal label volai, and OpenAPI now describes it; the source field description says the value inbound never occurs for messages. The MCP server instructions, SKILL.md and the llms files say the same. API behaviour is unchanged.
• 8 Oct 2026 (1.32.0): Save an explicit allowlist of owned active engine agents for returning callers with a unique real outbound call from this number within lookbackSecs (60-604800 seconds). Unknown, ambiguous or unverified callers keep the default agent. Empty agentIds disables the policy. Optional firstMessage applies only to verified callbacks. engineSyncRequired: true means the default agent engine configuration must separately activate webhooks.inbound_route_url with readback; this request does not rewrite live engine configuration. Verified incoming calls expose callbackOf.callId and optional server-owned taskId and taskItemId in call details. New REST GET/PUT /v1/numbers/{e164}/callback-routing and MCP get_callback_routing / set_callback_routing. Signed incoming tool context carries direction=in and empty dispatch/task/item fields. Server-owned volai_call_mode=campaign_callback is set only for verified callbacks. Verified inbound human contact stops later scheduled retries of the same task item without creating an outbound attempt or charge. An already running call and its billing finish normally. The server-owned dispatch/task/item binding is retained for eight days to cover the callback window.
• 8 Oct 2026 (1.31.0): POST /v1/tasks, PATCH /v1/tasks/{id}, create_task and update_task accept optional retryPolicy: "lorela_enterprise" and expiresAt (positive safe-integer Unix milliseconds); both fields are returned in the public task. Without a policy, maxAttempts remains 1-3 with a creation default of 1; with the policy it is 1-4 with a creation default of 4. PATCH without a limit preserves it. The policy can be enabled only before the first dispatch attempt. The second attempt is no earlier than eight minutes after the first real attempt starts, within 08:00-22:00 Europe/Prague; the third uses the next other 08:00-09:00 or 17:00-19:00 window; the fourth uses the opposite window on the following calendar day. A narrower callingWindow, including weekdays, still applies. Only no_answer, missed, busy or completed voicemail without human contact can retry; uncertain results and engine failures need review. The policy rejects manual resolve with action: "retry" and stops calling five days after the first real attempt. expiresAt also works without a policy and prevents any new dial at or after the deadline, including the first attempt; a call already in progress finishes normally. DNC and automatic blocking after three failures within 24 hours are not bypassed, so the fourth attempt is not guaranteed.
• 5 Oct 2026 (1.30.2): A call for which the engine does not send caller_loop in the post-call (the caller first talked to the agent and only afterwards just a repeated message was left on the line) has endReason: "completed" and the regular price, like any other completed call. The fallback sync of a lost post-call (the engine's GET /v1/calls) now reads metrics.caller_loop_reported: the value 1 means the engine sent caller_loop in the post-call, and caller_loop is taken over as before; the value 0 means an ordinary call, which is closed and billed with endReason: "completed" regardless of metrics.caller_loop_released. For an older engine without this field, the existing rule with metrics.caller_loop_released applies (a positive value means an ordinary call). REST and MCP response shapes, the endReason values and the outcome filter do not change.
• 4 Oct 2026 (1.30.1): endReason: "caller_loop" and priceHal: 0 are now given only to an inbound call with a positive durationSecs; an outbound call, or a call with zero duration, for which the engine sends termination_reason: "caller_loop" takes the regular path (endReason: "completed" and regular billing; a zero-duration call stays unclosed as before). The fallback sync of a lost post-call (the engine's GET /v1/calls) takes over caller_loop only when metrics.caller_loop_released is missing or 0; with a positive value (a person spoke up during the wait) the call is closed and billed like any other completed call with endReason: "completed", and call.completed carries the price, the same as when the post-call arrives on its own. A call with endReason: "caller_loop" is never listed in the portal among calls needing attention (Overview and the Calls filter), and the weekly e-mail summary does not count it as a handled call or a caller and does not list it among calls that need a reaction. REST and MCP response shapes, the endReason values and the outcome filter do not change.
• 4 Oct 2026 (1.30.0): New endReason: "caller_loop" value (REST GET /v1/calls and GET /v1/calls/{id}, MCP list_calls and get_call, webhook call.completed): an inbound call whose caller was an automated system repeating the same message (a queue, a dialer), ended by the engine's guard. The source is metadata.engine.termination_reason: "caller_loop" in the engine's post-call (for a lost post-call, the same field from the engine's GET /v1/calls). The call has status: "completed", a positive durationSecs and priceHal: 0, and no credit is charged; the price of 0 applies up to five minutes of call duration - a longer call is billed at the regular rates and keeps endReason: "caller_loop". The call.completed webhook carries endReason: "caller_loop". A call where a person spoke up during the wait and the engine carried on with them does not get caller_loop. In the outcome filter (GET /v1/calls, list_calls) such a call counts as agent.
• 4 Oct 2026 (1.29.6): PATCH /v1/agents/{id}, update_agent and draft publish: changing language 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, for an agent with provider: "elevenlabs", the same post-save engine switch attempt as turning on transferTo. On success the agent has provider: "engine" and the engine's default voice for the new language (milena, katarina); on failure it stays on ElevenLabs. A change between cs and sk moves nothing. voicemail_requires_engine has new wording: on creation it points to useForOutboundTasks: true, on an existing agent to support.
• 4 Oct 2026 (1.29.5): POST /v1/agents and create_agent return a new code elevenlabs_by_explicit_choice ({code, message: {cs, en}}) in warnings when the request sent useForOutboundTasks: false, the deployment default would have picked the engine for the agent's language, and the agent really stayed on ElevenLabs (a transferTo handoff may have switched it to the engine). The agent is created as before and the code blocks nothing. PATCH /v1/agents/{id}, draft publish and rollback never return it.
• 3 Oct 2026 (1.29.4): Documentation only, the API behavior does not change. maxAttempts (1-3) is the highest number of automatic dials of one contact, the first call included; 1 means no retries. A contact that you give resolve with action: "retry" after its attempts are used up gets one more dial. Every attempt where the call could have happened counts (unanswered, declined by the person called, or with an uncertain result). An attempt rejected before dialing does not count and has items[].attempts[].countsAsAttempt: false.
• 3 Oct 2026 (1.29.3): For attempts recorded from this version on, items[].attempts[].countsAsAttempt is false for every code where the call provably never happened, so they do not count toward maxAttempts: agent_not_found, agent_no_number, insufficient_credit, invalid_number, unsupported_country, blocked_destination, on_dnc, destination_auto_blocked, cannot_call_own_number, cannot_call_volai_number, capacity_busy, call_rejected, validation, rate_limited, relay_lease_limit, invalid_workflow, engine_not_configured and destination_busy. Previously the permanent problems with the number (invalid_number, unsupported_country, blocked_destination, on_dnc, destination_auto_blocked, cannot_call_own_number, cannot_call_volai_number) were counted, so after lifting a block and another rejection a contact showed more attempts than allowed although nothing was dialed. Attempts written before this version are not rewritten retroactively (the exception is an attempt whose dial intent the accounting repair closes). Uncertain dial errors (for example engine_unavailable) still count, because the call may have happened. A permanent problem still sends the contact to review (you decide), a repairable code (missing credit, an agent without a number and the like) pauses the task; rate_limited and relay_lease_limit leave the task running and only wait. Nothing is dialed in a loop because of this. A contact you return via resolve with retry after its attempts are used up now stays pending after a repairable dial error without a call (for example insufficient_credit) and is dialed again once the cause is fixed; before, it stayed failed and the task could not be started (task_not_startable).
• 3 Oct 2026 (1.29.2): destination_busy while dialing from a task (the call provably never happened): the contact keeps waiting (failed when it already had a counted attempt and has another free one, otherwise pending) with items[].lastError: "destination_busy" and items[].nextAttemptAt from the remaining time of the number lock (at least 30 s, at most 16 min, 90 s without a lock), the attempt has countsAsAttempt: false, the reservation in reservedBudgetHal is released and the other contacts keep running; the task's lastError is not set, only a stale waiting rate_limited or relay_lease_limit is cleared, because a busy result proves the limit passed. After the 6th busy result in a row (5 waits) the contact goes to review with reviewReason: "dial:destination_busy". The seven permanent codes (on_dnc, destination_auto_blocked, cannot_call_own_number, cannot_call_volai_number, invalid_number, unsupported_country, blocked_destination) send the contact to review with reviewReason: "dial:<code>", but the task stays running and moves to needs_attention only when no other work is left (previously immediately). Over the API and MCP a block is lifted with two calls: POST /v1/dnc/{e164}/unblock (unblock_destination), then resolve with action: "retry" (resolve_task_item); for your own number, a number of another volai account, an invalid number, a number outside Czechia and Slovakia and a premium-rate line only skip helps. A contact in review can now appear while the task is still running; resolve then returns 409 task_not_editable, so wait for needs_attention or pause the task. POST /v1/calls does not change.
• 2 Oct 2026 (1.29.1): items[].providerCallId points only to the call of the latest attempt: a contact in failed that is waiting for another attempt does not carry it; the call of every attempt stays in items[].attempts[].providerCallId. Previously the item kept the call of the first attempt, the next dialed call was not recorded on the task, and the contact was dialed again without counting the attempt and without adding the price to spentHal. The errors on_dnc, destination_auto_blocked, cannot_call_own_number and cannot_call_volai_number while dialing from a task are provably no call: the attempt gets outcome: "failed", the reservation in reservedBudgetHal is released right away and the contact goes to review with reviewReason: "dial:<code>" (previously outcome: "unknown" and a held reservation). POST /v1/tasks/{id}/start no longer returns 409 task_needs_attention because of a reservation that no contact holds; POST /v1/tasks/{id}/reconcile settles such a reservation and also closes an older open dispatch intent left after an attempt that was never dialed.
• 2 Oct 2026 (1.29.0): New endpoint POST /v1/numbers/orders/{id}/cancel (no body) and MCP tool cancel_number_order: a pending order moves to the new status cancelled (a new status value of the order in GET /v1/numbers/orders and list_number_orders); provisioning returns 409 in_progress, done and failed 409 invalid_transition, a foreign or unknown id 404 not_found; cancelling again returns the order unchanged. A cancelled order no longer counts toward the first top-up gate (one number per account without a top-up). callingWindow.end of tasks is inclusive of the whole minute (current <= end): a 00:00-23:59 window covers the whole day and window_closed no longer occurs in the end minute itself.
• 30 Sep 2026 (1.28.1): PATCH /v1/numbers/{e164} (MCP set_number_routing) with mode: "forward" returns 402 insufficient_credit when the account has never topped up and the number is not forwarded yet. A number that is already in forward can be pointed at a different target without a top-up. POST /v1/numbers (MCP buy_number) and POST /v1/numbers/orders (MCP order_number_from_region) return 402 insufficient_credit when asked for an additional number while an account without a top-up already holds an active number or has an open order (pending, provisioning). Same code and cause (account) as for SMS, different message text - it says what to do (make the first credit top-up); nothing is charged. After the first credit top-up (card, auto top-up) the restriction is gone.
• 25 Sep 2026 (1.28.0): New suspended: boolean field on the agent object (REST and MCP, GET/POST/PATCH /v1/agents). New error codes agent_suspended and account_suspended (403, cause: "account") - account_suspended on every REST call with an API key and every MCP tool (after the rate limit) except reading tax documents (GET /v1/billing/documents, /{id} and /{id}/pdf, the MCP tools list_billing_documents and get_billing_document), which stay available; agent_suspended on POST /v1/calls, POST /v1/agents/{id}/test-call and POST /v1/tasks/{id}/start. An inbound call blocked by a suspension of the agent or the account carries endReason: "suspended" (a new value next to credit_blocked, price 0). An account_suspended/agent_suspended response is never stored under an Idempotency-Key, so the same key succeeds once restored. Custom variable keys (variables on POST /v1/calls and make_call) can no longer start with the volai_ prefix - it is reserved for variables volai fills in itself (such as volai_block_reason), and such a request returns 400 validation; in tasks, such a key is only refused when the contact is dialed. Suspending and resuming is done only by the operator in the admin panel - there is no REST or MCP tool for it. The sentence a caller hears on a blocked line (debt or suspension) is now spoken in the agent's language (cs, sk, en, de, pl).
• 25 Sep 2026 (1.27.3): No interface change: the same warnings code agent_misuse_suspected in the same REST and MCP responses, only broader recognition.
• 24 Sep 2026 (1.27.2): Outbound tasks: relay_lease_limit from dialing (the quota of 2 concurrent agent calls per account) now behaves like rate_limited - the task stays running, sets lastError: "relay_lease_limit", the attempt does not count (countsAsAttempt: false) and waiting contacts get items[].nextAttemptAt one minute later. Previously the item went to review with reviewReason: "dial:relay_lease_limit" and the task to needs_attention. The engine sync (GET /v1/calls) reads the new attempt_id field of an outbound call and uses it to match an initiated record after an uncertain dial (no call_sid, also for an agent without its own number); once matched, call.completed is sent with the price and the relay line and quota are released. Requires an engine that lists attempt_id; an older listing behaves as before.
• 24 Sep 2026 (1.27.1): POST /v1/calls with agentId on an agent on volai's own engine, a trial call with systemPrompt, MCP make_call and outbound tasks: when dialing on the engine ends with a timeout, a dropped connection, a 500/504 response or an unreadable 2xx, the response is still 502 engine_unavailable, but the call stays initiated (no priceHal), the relay line is not released and the same to stays locked for 15 minutes (destination_busy); the concurrent call quota is released right away. If the call happened, the post-call or the engine sync fills in the outcome and price (the post-call now finds it by the attempt identifier even without a call_sid, including agents without a number of their own) and call.completed is sent; if not, the watchdog closes it after 2 h as failed with priceHal: 0. The call.failed webhook is not sent for an uncertain dial. A certain failure (no connection to the engine at all or a timed-out connection attempt, 4xx, 502/503) behaves as before: failed, priceHal: 0, call.failed.
• 24 Sep 2026 (1.27.0): New warnings code agent_misuse_suspected ({code, message: {cs, en}}). Appears in POST/PATCH /v1/agents, PUT /v1/agents/{id}/draft, POST /v1/agents/{id}/simulate, POST .../draft/publish, POST .../draft/rollback, POST /v1/calls (the trial call prompt or variables), POST/PATCH /v1/tasks, POST/PATCH /v1/tools and the matching MCP tools (create_agent, update_agent, save_agent_draft, simulate_agent_draft, publish_agent_draft, rollback_agent_draft, make_call, create_task, update_task, create_tool, update_tool). The warnings field is optional, absent when there is nothing to flag, and /openapi.json describes it on all of these responses.
• 24 Sep 2026 (1.26.3): POST /v1/calls with from (bridge) and MCP make_call: when the connection order to the phone operator ends with a network error, a timeout or a 429/5xx response, the call is returned as a success with status: "initiated" instead of 502 callback_failed and stays initiated until cdr-sync pairs it with the CDR (and bills it), or the watchdog closes it after 24 h as failed with priceHal: 0. callback_failed now means only a provable rejection by the operator (an error response or 4xx). The call.failed webhook is not sent for an uncertain order; the same to number stays locked for about 10 minutes (destination_busy).
• 24 Sep 2026 (1.26.2): The per-account cap on calls within 24 hours (shared by POST /v1/calls with an agent or a bridge, relay and trial calls, MCP make_call and outbound tasks) is now 1000 instead of 200. Exceeding it still returns 429 rate_limited with the daily-limit message; 10/min, concurrency and the engine budget are unchanged.
• 24 Sep 2026 (1.26.1): Outbound tasks: a call record in failed with no conversationId and no priceHal (the engine refused or did not confirm the dial) now settles at 0 in reconcile - previously the item kept reviewReason: "billing_unknown" and the task stayed needs_attention forever. resolve with skip on a billing_unknown item moves a task with remaining work to paused (the original call's reservation keeps counting in reservedBudgetHal, and start accepts it); retry still waits for the price. A decision right after a dial error (reviewReason: "dial:...") no longer loses the link to the call or its reservation. rate_limited while dialing (engine limit, 10 calls per minute, 200 per day) keeps the task running with lastError: "rate_limited" and sets waiting items' nextAttemptAt to the end of the limit (from Retry-After, otherwise in 5 minutes, at most 24 hours) instead of paused; the attempt does not count. invalid_workflow and engine_not_configured while dialing are provably no call (the task becomes paused, the attempt does not count). Every call by an agent on volai's own engine that the engine never dialed (outbound tasks as well as POST /v1/calls, MCP make_call and the portal) has priceHal: 0 and durationSecs: 0 in GET /v1/calls instead of missing values; the call.failed webhook is unchanged.
• 24 Sep 2026 (1.26.0): POST /v1/calls with agentId on an agent on volai's own engine (and MCP make_call): a rejection by the engine's outbound-minute limit (hourly and daily bucket per account) or by full engine concurrency is now 429 rate_limited instead of 502 engine_unavailable; the minute limit adds a Retry-After header (seconds until the end of the hourly window, or until midnight UTC for the daily one). Nothing was dialed or charged; the call stays in the history as failed and the call.failed webhook carries reason: "rate_limited". Outbound tasks treat rate_limited (including the 10 calls/min and 200/day limits) as provably no call: the item is failed without counting an attempt, and the task is paused instead of needs_attention. The POST /v1/calls error table now also lists 502 engine_unavailable - for an agent on volai's own engine it means only a real engine outage, not a limit.
• 23 Sep 2026 (1.25.0): New optional event_id field in the webhook envelope ({event, data, ts, event_id}) for call.completed/call.failed/call.no_answer/call.missed - message.sent and the webhook.test test event are unchanged. A failed delivery of those four events no longer stops after 3 attempts (3s apart): it stays queued and retries over the following minutes, up to 5 rounds; a repeat delivery carries a byte-identical body. GET /v1/webhook/deliveries (and MCP list_webhook_deliveries) now also show rounds before the final one, attempts is the sum of attempts across all rounds, and there is a new optional eventId field.
• 23 Sep 2026 (1.24.1): Two new warnings codes: prompt_variables_unavailable_inbound (an agent with numberE164 whose systemPrompt/firstMessage uses a {{variable}} outside the set an inbound call actually supplies) and first_message_empty (a firstMessage with no letter or digit left in it outside the variables once every {{...}} block is removed). Both REST (POST/PATCH /v1/agents, publish and rollback) and MCP (create_agent, update_agent, publish_agent_draft, rollback_agent_draft) read the same source as the portal's agent editor (agentWarnings).
• 20 Sep 2026 (1.24.0): New optional busyCalendarIds field on the agent (POST/PATCH /v1/agents, MCP create_agent/update_agent, drafts) and on agent-less slot search and booking (POST /v1/integrations/{id}/availability, POST /v1/integrations/{id}/events, MCP find_free_slots, create_calendar_event). The calendars are read in parallel; if any of them fails, the whole lookup fails, so no time is offered over an event we simply could not see. At most four, without duplicates and without calendarId; otherwise 400 calendar_invalid_rules, an unknown calendar 400 calendar_invalid_calendar.
• 20 Sep 2026 (1.23.4): The error tables of POST /v1/agents, PATCH /v1/agents/{id} and draft publish/rollback add the six codes validateCalendar returns: 404 calendar_integration_not_found and 400 calendar_invalid_calendar, calendar_invalid_timezone, calendar_invalid_windows, calendar_no_windows, calendar_invalid_rules. This flows into openapi.json, the /docs/api reference, SKILL.md and llms-full.txt.
• 20 Sep 2026 (1.23.3): maybeQueueMissedCallSms now also fires for an outbound call with answeredBy: "voicemail" (previously only status: "no_answer" and inbound missed). A voice menu (ivr) or unknown does not trigger it. All other conditions (CZ/SK number only, DNC, blocked destinations, one SMS per number per 24 h, quiet hours, last task attempt) are unchanged; CallRecord.missedSms is written the same way.
• 19 Sep 2026 (1.23.2): A timestamp with milliseconds was formatted with a time zone offset one minute short (+01:59 instead of +02:00) - this affected the now field in the agent tools and the start of a created event when a client sent start with fractional seconds. Alternatives returned with 409 calendar_slot_taken (POST /v1/integrations/{id}/events, MCP create_calendar_event) are now computed from the requested time, the same as find_free_slots with a time.
• 19 Sep 2026 (1.23.1): The agent calendar field (POST/PATCH /v1/agents, MCP create_agent/update_agent and drafts) rejects a calendar whose accessRole is reader or freeBusyReader with 400 calendar_invalid_calendar, because the agent writes appointments into the same calendar. list_calendars returns the role as accessRole where the provider reports it; a calendar without a role is accepted as before. No other error codes change.
• 19 Sep 2026 (1.23.0): New CallRecord.rating field (value: "good" | "bad", reason?, note?, at, source: "portal" | "email" | "api" | "mcp") and CallRecord.missedSms; PATCH /v1/calls/{id} and MCP annotate_call accept rating/ratingReason/ratingNote (patchCallAnnotation calls rateCall with source: "api"/"mcp"). New AgentRecord.missedCallSms { enabled, text? } field (variables {firma}, {cislo}, {agent}) on POST/PATCH /v1/agents, GET /v1/agents/{id} and MCP create_agent/update_agent/get_agent/save_agent_draft. GET/PATCH /v1/account and MCP get_account/update_account have companyName (max 80 chars, empty string clears it), and GET now returns notifications.weeklySummary. The test call in the agent editor shows the outcome based on the call goal (call.evaluation.goal) and the collected data.
• 18 Sep 2026 (1.22.0): New endpoints POST /v1/integrations/{id}/availability (free slots without a saved agent - windows omitted means 24 hours every day) and POST /v1/integrations/{id}/events (create an appointment, requires confirm: true, optional idempotencyKey for safe retries; 409 calendar_slot_taken on a collision), MCP tools find_free_slots and create_calendar_event with the same shape. DELETE /v1/integrations/{id} now returns affectedAgents - agents whose calendar field was turned off by disconnecting this integration. New calendar field on POST/PATCH /v1/agents, GET /v1/agents/{id} and MCP create_agent/update_agent/get_agent: integrationId, calendarId, timezone, slotMinutes, minNoticeMinutes, horizonDays, bufferMinutes, windows (an array of {from,to} windows per weekday). Works only on volai's own engine (provider: "engine") - on an agent hosted on ElevenLabs the field is saved and waits for the calendar_pending_engine_switch warning until the agent switches. Eleven new error codes with cause/action: calendar_slot_taken, calendar_confirmation_required, calendar_invalid_range, calendar_integration_not_found, calendar_invalid_calendar, calendar_invalid_timezone, calendar_invalid_windows, calendar_no_windows, calendar_invalid_rules, calendar_too_many_events, calendar_unavailable.
• 18 Sep 2026 (1.21.0): New ledger movement type setup_revision (GET /v1/credit/ledger, MCP) for a done-for-you setup order's revision round beyond the package, amount SETUP_EXTRA_REVISION_HAL (490 CZK excl. VAT). Tax documents (GET /v1/billing/documents, .../{id}, list_billing_documents, get_billing_document) now always carry a kind field ("invoice" - default, or "credit_note"), plus optional correctsNumber and correctionReason fields; a done-for-you setup refund's credit note is numbered in its own OD series and carries positive amounts (the minus sign is added by the PDF). credit() (lib/service/balance.ts) gained an internal notifyTelegram parameter - a done-for-you payment now sends just one Telegram alert ("Na klíč: zaplaceno"), not two. New public landing page at /receptionist-done-for-you (Czech canonical /recepcni-na-klic).
• 18 Sep 2026 (1.20.0): New laughter field (auto/on/off) on POST/PATCH /v1/agents and MCP create_agent/update_agent: auto follows the engine's sensitive-topic detection (debt collection, healthcare, authorities, funeral services), on overrides that detection, off always suppresses it; an omitted key is stored and returned as auto, never absent. GET /v1/agents/{id} and the new MCP tool get_agent (previously missing parity for a single agent's detail) add laughterEffective ({active, reason, sensitiveCategory} | null) nested inside the returned agent object, computed fresh for the published configuration; null means it could not be determined right now (the engine did not respond within 3 seconds, was down, or returned a silent 404 on an older build) - never a guess. MCP update_agent returns the same object as a top-level field next to agent instead, since PATCH /v1/agents/{id} never returns it. The field is accepted and stored for an agent on ElevenLabs too, but has no audible effect there - only a Czech Cartesia voice on volai's own engine plays it.
• 18 Sep 2026 (1.19.0): New REST API v1 and MCP area - source setup-orders, capability area setup (after credit). Seven endpoints (POST /v1/setup-orders, GET /v1/setup-orders, GET/POST /v1/setup-orders/{id}, .../messages, .../checkout, .../launch, .../cancel) and seven matching MCP tools (create_setup_order, list_setup_orders, get_setup_order, message_setup_order, checkout_setup_order, launch_setup_order, cancel_setup_order) over the same service layer, lib/service/setup-orders.ts. The quote is always computed by the catalog in code (lib/setup-catalog.ts); the model only picks items from the conversation. New error codes: setup_order_not_found, order_closed, invalid_transition, quote_pending_confirmation, checkout_open, turn_in_progress, advisor_no_quote, advisor_unavailable, setup_orders_disabled. Documentation at /docs/done-for-you (Czech /docs/na-klic).
• 17 Sep 2026 (1.18.0): The agent draft (PUT/GET /v1/agents/{id}/draft, POST /v1/agents/{id}/draft/publish) and the MCP save_agent_draft tool now treat numberE164 as three-state: an absent key leaves the agent's number untouched, null disconnects it, and a string attaches that number - parity with the semantics PATCH /v1/agents/{id} already had. Reading a draft also reconciles it against the live agent: published.numberE164 always mirrors the live number, and draft.numberE164 does too whenever the draft made no explicit choice, so the editor's pre-publish check and outbound tasks see the true state even after a number was attached or moved outside the editor; "no explicit choice" also covers a string that matches the agent's current LIVE number - that value behaves the same as an absent key, re-checked on every draft read against whatever number is live at that moment; if the number later moves to a different agent outside this draft, the same stored value becomes an explicit choice again and the next publish or rollback reattaches it here - not silently: publish and rollback responses (REST and both MCP tools) now carry a new number_changed_by_publish warning with from/to (E.164, or null for no number) in that case, without blocking the operation either. One read-side compatibility note: draft.numberE164 can now come back as null (an explicit "no number" choice) where the key used to be simply absent - treat it the same as an absent key, meaning the agent has no number. The "tested" marker and the agent fingerprint pinned to a running outbound task are now computed WITHOUT the phone number too (behaviorFingerprint, not draftFingerprint), so attaching or moving a number outside the editor no longer requires a fresh test and no longer stops a running campaign; a draft with a number saved BEFORE this change has its marker computed the old way, including the number, so it asks to be re-earned once - one test or publish after the update restores it, and the new rule applies from then on.
• 15 Sep 2026 (1.17.0): A new goal display state, GoalDisplayState (success/failure/unclear/no_conversation/not_evaluated), replaces the AgentGoalResult triple in the portal's display, in the /hovory filters and in the overview. REST and MCP gained answeredBy: "ivr", goal.reason ("no_caller_speech"/"evaluation_error"), and hasConversation (boolean | null). The goal parameter (GET /v1/calls, MCP list_calls) accepts five new values alongside the existing unknown, which stays backward compatible - it still covers records with no clear result (goal.result missing or unknown): always unclear and not_evaluated, and no_conversation only when its result is also unknown.
• 13 Sep 2026 (1.16.0): A new endReason: "engine_error" value (status failed) appears when the engine sends metadata.engine.termination_reason as engine_stall or engine_error for a call that was actually handled - previously that field was discarded for such calls. priceHal is set to 0 only when the call has no price yet (otherwise it is left unchanged, with an ALERT log). The call.failed customer webhook gained four new optional fields: durationSecs, priceHal, transcript, summary - populated only for this technical branch, missing everywhere else as before. GET /v1/calls/{id} and MCP get_call return the same endReason value. Outbound tasks (POST /v1/outbound-tasks, MCP) treat engine_error as a retryable attempt (the same path as no_answer), not a reason to stop the campaign, and do not record it toward the automatic 30-day destination block.
• 13 Sep 2026 (1.15.0): POST/PATCH /v1/agents and the MCP create_agent/update_agent/save_agent_draft tools take a new silencePromptSecs: number | null field (a whole number 3 to 25, null turns it off), bounds matching the engine (engine/types.py, U1). A missing field on POST/create_agent saves the default of 10 - unlike voicemail, the field is accepted and returned for EITHER provider (GET /v1/agents returns the stored value even for provider: "elevenlabs"). A value outside the bounds fails with the generic validation error (validation, 400), no new code. Existing agents on the engine get the default of 10 via a one-off re-sync script (scripts/resync-silence-prompt.mts) that changes only this one field.
• 13 Sep 2026 (1.14.7): OpenAPI adds descriptions to every operation and request field, including nested variants. Agent, tool, SMS and call constraints use product limits shared with the service layer instead of permissive parser ceilings. Automated checks validate all request and response examples against their schemas. API behavior, error codes and provider settings are unchanged.
• 13 Sep 2026 (1.14.6): POST /v1/messages and MCP send_sms return insufficient_credit (HTTP 402, cause account) until the account has a positive topup (card or auto top-up) or admin (manual owner adjustment) ledger entry. The previous cap of 3 SMS for accounts without an active number of their own is gone, and an active number no longer grants an exception. The first top-up is kept as a permanent account flag, so a long ledger history never blocks a customer.
• 13 Sep 2026 (1.14.5): New workflow_node_tool_missing code in warnings on POST/PATCH /v1/agents, on draft publish and rollback, and on MCP create_agent, update_agent, publish_agent_draft and rollback_agent_draft. It applies to both providers, because a deleted tool does not reach the phase on volai's own engine either. workflow_node_tool_not_synced now only covers a tool that is on the account but not among the agent's own. The Reception template also recommends two sentences for the base prompt: do not guess operational details, and ask about one thing at a time.
• 12 Sep 2026 (1.14.4): Setup distinguishes OAuth grant identifiers from API keys when restoring older saved choices. An unavailable status check is not treated as revoked access.
• 12 Sep 2026 (1.14.3): Added the catalog files katty-studio.mp3 and katty-telefon.mp3 using the same generator and content as the other voices. The agent voice, provider and phone service settings are unchanged.
• 12 Sep 2026 (1.14.2): Copy labels and next-step guidance match the selected connection method. Codex desktop with an API key points to config.toml. Closing the mobile menu preserves focus restoration.
• 12 Sep 2026 (1.14.1): Sign-in preserves the assistant setup destination. The workspace preference is stored per account separately from actual MCP verification. Manual guides cover Claude Code, Codex CLI and desktop, with API keys as an alternative. Help and the names Voice agents, Phone numbers and Data & integrations are consistent.
• 12 Sep 2026 (1.14.0): When useForOutboundTasks is omitted, selection depends on VOLAI_ENGINE_DEFAULT_FOR_NEW, engine availability and VOLAI_ENGINE_DEFAULT_FOR_NEW_LANGUAGES (unset means cs,sk). Language alone does not guarantee the engine. Explicit true requests the engine; false starts on ElevenLabs. Applies to the portal, POST /v1/agents and MCP create_agent. Read back provider and voiceId after creation; handoff may trigger a subsequent provider switch attempt.
• 12 Sep 2026 (1.13.0): The workflow field is available in POST and PATCH /v1/agents, in the agent draft, and in the create_agent, update_agent and save_agent_draft MCP tools. A call that went through phases carries workflowPath in GET /v1/calls and GET /v1/calls/{id}. New workflow_*, workflow_not_synced_to_provider and workflow_node_tool_not_synced warnings flag phase configuration issues.
• 12 Sep 2026 (1.12.5): voiceId for an ElevenLabs agent: katty (default, the template voice) or a raw ElevenLabs id; jana is gone from the catalog and from ElevenLabs (the two agents from the afternoon of 12 Sep were switched to Katty and the voice was removed from the workspace). GET /v1/voices?provider=elevenlabs and MCP list_voices with provider: elevenlabs return katty. The engine's ElevenLabs fallback for Milena, Tereza and Katarina is Katty as well.
• 12 Sep 2026 (1.12.4): Polling no longer interrupts a slow status request. Successful MCP read evidence is found by active access even if writing the helper index failed. Verification still requires get_balance or list_agents through MCP.
• 12 Sep 2026 (1.12.3): Fixed the English calendar privacy link and kept an active goal filter visible even without previous evaluations. Both languages have regression coverage for links and unavailable integrations.
• 12 Sep 2026 (1.12.2): The MCP guide uses existing evidence of successful reads through an active API key or OAuth grant, with no simulated verification. The goal=unknown filter in GET /v1/calls and MCP list_calls also includes records without a goal evaluation. Technical completion does not mean a goal was met. REST and MCP still return individual records; the portal groups them into conversations.
• 12 Sep 2026 (1.12.1): voiceId for an ElevenLabs agent: jana (default, the template voice) or a raw ElevenLabs id; anet passes only on an agent that already has it, otherwise a 400 validation with an explanation (previously a 502 eleven_labs_error from ElevenLabs voice_live_moderated_not_allowed). GET /v1/voices?provider=elevenlabs and MCP list_voices with provider: elevenlabs return jana. An ElevenLabs agent without voiceId gets Jana explicitly (the record carries her id). SIP registration: the carrier returned 403 INVALID_USER for lines bought through its API until the line's SIP protocol was toggled off and on once; fixed for all lines and done automatically when a new line is bought.
• 12 Sep 2026 (1.12.0): OAuth authorization code + PKCE S256, DCR, resource-bound opaque tokens, refresh rotation/replay detection, OIDC discovery/JWKS/userinfo and revocation. Access tokens last 10 minutes, refresh tokens up to 30 days, grants up to 90 days. Password changes invalidate OAuth access. MCP annotations explicitly distinguish overwrites, paid actions, messages and external side effects.
• 12 Sep 2026 (1.11.0): GET /v1/numbers/{e164}/sip and MCP get_sip_credentials: outboundTrunkAddress = sip.volai.cz (volai's own SIP proxy with digest auth, realm sip.volai.cz; measured: the platform refuses an INVITE larger than the UDP MTU, the same call passes over TCP), transport = tcp (schema is now enum [tcp, udp], UDP works too), port 5060 unchanged. The watchdog monitors the proxy healthz (SIP_PROXY_HEALTHZ_URL): ops e-mail when unreachable, when the auth data sync stalls or when the certificate has under 14 days left. The ElevenLabs post-call webhook has its HMAC secret in production and is enabled per agent (ELEVENLABS_POST_CALL_WEBHOOK_ID).
• 12 Sep 2026 (1.10.0): GET /v1/numbers/{e164}/sip and MCP get_sip_credentials: outboundTrunkAddress is driven by its own configuration (it may equal server), field descriptions no longer mention a realm; inboundSignallingCidrs unchanged. The ElevenLabs post-call webhook matches inbound calls via metadata.phone_call.call_sid (it used to read the SIP Call-ID call_id, which never matched the call:sid key written by the initiation webhook) through findExistingCallByKeys shared with the conversations-sync cron (order call:conv -> call:attempt -> call:sid). Per-agent post-call webhook settings (platform_settings.workspace_overrides.webhooks) are migrated by the cron once ELEVENLABS_POST_CALL_WEBHOOK_ID is set; until then the cron keeps closing calls. The engine post-call accepts phone_call.external_number: null and caller_presentation; the uri_ caller prefix is stripped as in the initiation webhook. The call transfer target (transfer_to_number) is built from a separate VOLAI_SIP_TRANSFER_HOST, not from the public SIP domain. New internal source of auth data for the SIP proxy (GET /api/internal/sip-subscribers, outside v1, bearer + IP allowlist + rate limit).
• 12 Sep 2026 (1.9.0): POST/PATCH /v1/agents and MCP create_agent/update_agent can now return a second warnings code: first_message_too_long, independent of first_message_no_ai_disclosure - and publishing an agent draft (POST /v1/agents/{id}/draft/publish, MCP publish_agent_draft) and rolling it back to an earlier revision (POST /v1/agents/{id}/draft/rollback, MCP rollback_agent_draft) now return the same warnings too, which they previously omitted entirely - both of them write the first line to the live agent. The estimate counts words, digits per character, and all-caps abbreviations up to four characters; a longer all-caps word counts as one word, so a company name written in capitals no longer inflates the estimate. The single threshold (an estimated duration over 7 seconds) is measured against what the caller actually hears - the greeting plus the call-recording notice, when enabled. An unchanged default greeting template never gets the warning, only a line the customer has edited.
• 12 Sep 2026 (1.8.2): Documentation, integration guides and error actions point to AI assistant for access management. MCP makes clear that the voice engine is required to start an outbound task; a task can also be created with an ElevenLabs agent.
• 12 Sep 2026 (1.8.1): OpenAPI now describes Idempotency-Key for 14 supported operations, response headers and the optional revision JSON body when deleting a task. Documentation corrections without changing paid-action behavior: useForOutboundTasks distinguishes true/false/omission, tasks support 1000 recipients and billing_unknown retains the original call and reservation until its price is known. Credit tax documents are available over REST and MCP; an API key can revoke only itself over REST; integration disconnect is REST/portal. Correction to 1.6.1: preview_task_csv is not an MCP tool; use POST /v1/tasks/csv-preview or the portal. Install commands share the onboarding generator, example tabs have unique anchors and Python preserves JSON values.
• 11 Sep 2026 (1.8.0): The new REST POST /v1/dnc/{e164}/unblock and the corresponding MCP tool unblock_destination lift an automatic destination block; they also work for blocks created before this deployment. Older blocks may be absent from GET /v1/dnc and list_dnc because they predate the listing index, but direct unblock by phone number still works. Indexed blocks are returned in a blocked: [{e164, blockedAt, expiresAt}] array (times are Unix milliseconds) alongside the unchanged numbers. After a block is lifted, the failed-attempt counter starts over - three new failed attempts to the same number block it again, and lifting it again is not limited. groupCallsByConversation (the shared primitive behind /hovory, the CSV export, the Previous/Next navigation, and the stats) now sorts by representative.startedAt descending; it used to sort by key, i.e. alphabetically by conversation id. TestCallOutcome has a new no_answer value kept separate from failed, so the panel never claims a cause it doesn't know. A name written in ALL CAPS now gets an ALL CAPS vocative form (RADEK -> RADKU) in both the e-mail and the Overview header.
• 11 Sep 2026 (1.7.1): agent_busy (HTTP 409, cause: "busy") was added to the shared error map PUBLIC_ERROR_HTTP/PUBLIC_ERROR_CAUSE (lib/types.ts). It is returned by switchAgentProvider (lib/service/engine-provider.ts) - the only portal admin action that switches an agent's provider; REST v1 and MCP have no such input (agents.switch_provider in the capability catalog, lib/capabilities.ts). The check uses a new GET /v1/calls/active client (lib/engine.ts listActiveCalls): the agent's call is matched PRIMARILY by the agent_id field, which the engine carries on an active call since the version that added it was deployed; the number stays a fallback for an older engine without it.
• 11 Sep 2026 (1.7.0): POST/PATCH /v1/agents and the MCP create_agent/update_agent/save_agent_draft tools take a new voicemail: {enabled, action: "mark"|"hangup"|"message", message?} field - only for an agent with provider: "engine", otherwise voicemail_requires_engine; message is required when action: "message", up to 400 characters (invalid_voicemail_message). GET /v1/agents returns the configured value. The engine's post-call now carries answered_by/voicemail_reason/voicemail_message_left/voicemail_detected_at_secs; answered_by takes precedence over the previous transcript-based estimate (lib/answered-by.ts) only with human and voicemail - unknown is treated as "the engine didn't decide" and the transcript-based estimate is used instead. GET/list_calls/get_call for an outbound call handled by the engine also return voicemailReason (a fourth value, human_reply, for a short human reply), voicemailMessageLeft, and voicemailDetectedAtSecs.
• 11 Sep 2026 (1.6.5): For an outbound call ended before answer the engine deletes the room and delivers a post-call webhook: empty transcript, call_duration_secs: 0 and the new additive field metadata.engine.termination_reason (no_answer or disconnected_before_answer). The call gets status: no_answer, endReason: no_answer and price 0 as before, only immediately. The GET /v1/calls reconciliation pairs engine outbound calls by call_sid and sends zero duration for calls that never connected. GET /openapi.json: answeredBy now carries a description about the outbound-only limitation.
• 11 Sep 2026 (1.6.4): POST /v1/tasks and PATCH /v1/tasks/{id} (and create_task/update_task in MCP) accept up to 1000 recipients, POST /v1/tasks/csv-preview up to 1000 rows. A new task record size check (2 MB of serialized JSON) returns validation with field recipients.
• 11 Sep 2026 (1.6.3): ElevenLabs initiation webhook: the payload's agent_id is now checked against the routed agent's elevenAgentId OR id - a foreign agent_id gets only a minimal response without conversation_config_override; the same check guards closing the conversation in the post-call webhook and the conversations-sync cron. CDR-sync cron: an unrecognized outbound CDR record from your own line (excluding the demo number), older than 600s and without an ambiguously matching existing record, is now billed as kind: "sip" at the outbound rate with no agent surcharge (it shows up in GET /v1/calls with kind: "sip"; the chargedSip counter is only in the cron's own response, not in the public API); a younger or ambiguously matching record is still just held for manual review. CallKind extended with "sip". The CDR shape of a real SIP client call has no production evidence yet (no registered softphone) - hence both safeguards.
• 11 Sep 2026 (1.6.2): New endpoint POST /v1/tasks/{id}/items/{itemId}/resolve with body { action: "retry" | "skip", revision } and the MCP tool resolve_task_item; new error code item_not_resolvable (409, account), task_not_editable for a running or completed task. The engine call sync matches the account's own outbound leg by relay line and start time, closes an unanswered outbound call as no_answer and releases the tenant concurrency quota after closing. relay_lease_limit while dialing a task is a transient state that does not consume an attempt.
• 11 Sep 2026 (1.6.1): POST /v1/tasks/csv-preview and the portal recognise the phone column regardless of case, surrounding spaces and a trailing colon and accept aliases (telefon, tel, mobile, phone number); the response always names the column phone. A single-column input without a header whose first value is a phone is treated as data. Without a phone column the preview returns a single phone error on the header instead of Phone is required on every row. The agent_not_ready contract is unchanged. Documentation correction, 12 Sep 2026: the original MCP-tool claim was incorrect; CSV preview is REST/portal-only.
• 11 Sep 2026 (1.6.0): GET /v1/numbers/{e164}/sip and the MCP get_sip_credentials tool now also return outboundTrunkAddress, port, transport and inboundSignallingCidrs alongside server/username/password; MCP create_relay_lease and the get_sip_credentials description now explicitly distinguish server (registration) from outboundTrunkAddress (a platform's outbound trunk). The /en/docs/bring-your-own-agent guide, the ElevenLabs integration page and the blog post no longer put server into outbound_trunk_config.address - only outboundTrunkAddress.
• 11 Sep 2026 (1.5.1): GET /v1/calls, GET /v1/calls/{id}, the call.completed webhook and MCP list_calls/get_call: answeredBy is present only when direction: "out" (older records included). POST /v1/messages and send_sms: an account without an active number and without a positive topup/refund/admin ledger entry gets insufficient_credit (HTTP 402, cause account) after three sent SMS.
• 8 Sep 2026 (1.5.0): New REST endpoints: GET/PATCH /v1/account, PUT /v1/account/billing, GET /v1/api-keys, DELETE /v1/api-keys/{id} (self-revoke); PATCH /v1/calls/{id} and GET /v1/calls extended with from, to, agentId, flagged, goal, outcome query parameters; POST /v1/tools/test, POST /v1/tools/{id}/test, DELETE /v1/webhook, and GET /v1/tools/{id} now additionally returns agents; POST /v1/agents/{id}/draft/rollback; GET /v1/numbers/{e164}, GET/POST /v1/numbers/waitlist, DELETE /v1/numbers/waitlist/{offerId}, GET /v1/numbers/{e164}/sip/status; POST /v1/integrations, DELETE /v1/integrations/{id}, POST /v1/integrations/{id}/events/{eventId}/propose; GET /v1/changelog (no API key, x-volai-version on every v1 response including errors, 429 and /openapi.json). 16 matching new MCP tools: get_account, update_account, update_billing_details, list_api_keys, annotate_call, test_tool, remove_webhook, list_webhook_deliveries, rollback_agent_draft, reconcile_agent_draft_operation, test_call, get_number, join_number_waitlist, leave_number_waitlist, get_sip_status, get_changelog - revoking someone else's API key, creating an API key, and disconnecting an integration or card stay REST-only or portal-only (spec §3). The new capability catalog holds a capability field on every endpoint and tool; guard tests verify the error table and response example on /docs/api match the real error codes for every endpoint. Additive only - no existing status or code changed. The new content/changelog.json file is the single source of truth: /en/changelog, the changelog section on /docs/api, the Versioning section in SKILL.md, RSS (/en/feed/<area>), GET /v1/changelog and the MCP get_changelog tool are all generated views over it. Additive only - no existing content disappeared. New REST endpoints: GET/POST /v1/tasks, GET/PATCH/DELETE /v1/tasks/{id}, POST /v1/tasks/{id}/start, POST /v1/tasks/{id}/pause, POST /v1/tasks/{id}/reconcile, POST /v1/tasks/csv-preview. 7 matching new MCP tools: list_tasks, get_task, create_task, update_task, pause_task, reconcile_task, start_task (which requires repeating the real recipient count and budget, otherwise it returns an error with the real numbers) - deleting a task and previewing a CSV stay REST and portal only (spec §3). Portal: a Delete task button on the task detail page with type-to-confirm. Additive only - no existing status or code changed. New REST endpoints: GET /v1/credit/ledger, POST /v1/credit/topup, GET/PATCH /v1/credit/auto-topup, POST /v1/credit/auto-topup/setup, POST/DELETE /v1/credit/auto-topup/card, GET /v1/billing/documents, GET /v1/billing/documents/{id}, GET /v1/billing/documents/{id}/pdf; GET /v1/balance now additionally returns runway and notice. 6 matching new MCP tools: list_ledger, create_topup_link, get_auto_topup, disable_auto_topup, list_billing_documents, get_billing_document (get_balance extended with the same runway/notice) - get_billing_document does not return the PDF, which stays REST-only via GET /v1/billing/documents/{id}/pdf (binary output); turning auto top-up on and changing its amount or card stay behind a Stripe Checkout link only, MCP has neither (spec §2, §3). Additive only - no existing status or code changed. GET /v1/account now returns a new notifications.productUpdates field (on by default); there is a matching toggle in portal Settings. The daily email digest (cron 0 6 * * * UTC) only sends to accounts with a verified email and productUpdates !== false, at most one email per account per day. The List-Unsubscribe header and cookie-free one-click unsubscribe now also cover the reactivation email when UNSUBSCRIBE_SECRET is configured on the server - without it the email still sends, just without the unsubscribe link. Additive only - no existing status or code changed.
• 8 Sep 2026 (1.4.3): Every input property of all 44 MCP tools carries its own description (clients see it in tools/list; the PATCH .../events/{eventId} and PUT /v1/agents/{id}/draft bodies expose it in openapi.json too). The invoice endpoints GET /v1/integrations/{id}/invoices[/{invoiceId}] list their error codes by real reachability in the docs and in OpenAPI - integration_storage_error was removed, it never came from the API - and their query validation returns the human-readable message like the rest of v1 (same for GET .../events). Additive only - no status or code changed.
• 8 Sep 2026 (1.4.2): Fixed Apple event reads and confirmed updates: iCloud rejects UID searches, so event lists now return opaque CalDAV resource IDs. Pass externalId unchanged as eventId; reload any Apple event IDs saved from earlier versions. Invalid Apple IDs return 400 calendar_invalid_query. Google identifiers are unchanged.
• 8 Sep 2026 (1.4.1): POST /v1/agents and create_agent accept useForOutboundTasks (choosing volai's own voice engine at creation, the same choice as the portal checkbox "Use for outbound tasks"; omitted = the deployment default, today ElevenLabs). Additive only - no status or code changed.
• 8 Sep 2026 (1.4.0): Apple Calendar shares the same calendar flow over REST and MCP as Google. Fakturoid and ABRA Flexi added GET /v1/integrations/{id}/invoices[/{invoiceId}] plus the list_invoices and get_invoice tools (the interface only reads invoices). GET /v1/integrations and list_integrations also return providers with setup readiness and a browser connection URL. Provider credentials still require connection in the portal. Additive only - no status or code changed.
• 7 Sep 2026 (1.3.0): Google Calendar entered the public interface - GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET/PATCH /v1/integrations/{id}/events/{eventId} and six MCP tools (list_integrations, list_calendars, list_calendar_events, get_calendar_event, propose_calendar_update, confirm_calendar_update), which takes REST to 50 endpoints and MCP to 42 tools. Every error response also carries cause (request / account / busy / service - who fixes it) and action (one sentence on what to do). validation messages name the field, the actual value and the accepted maximum instead of the raw validator text; the input caps for an agent's name, instructions, goal and knowledge are ten times the product limits, so the limit is always reported by the product error with the exact number. MCP errors carry the same fields in structuredContent.error (including requestId) and a text prefixed by cause. Additive only, no status or code changed.
• 6 Sep 2026 (1.2.0): The /v1/agents/{id}/draft* and /simulate endpoints lost the ok wrapper and plain-string errors - errors now share the same shape, {error:{code,message,requestId,docsUrl}}, as the rest of v1; revision in request bodies was renamed to expectedRevision; added hasMore/nextBefore pagination fields, X-Request-Id and RateLimit-* headers, POST /v1/webhook/test, GET /v1/webhook/deliveries, and GET /openapi.json. The draft endpoints were already public from 5 Sep 2026, but without a stable contract - they are therefore excluded from the versioning guarantee (rule 1 of the Versioning section) up to and including 1.2.0.

The full, continuously updated list lives on the Changelog page (also available as an RSS feed).

Conventions

Habits that hold across endpoints - not just at one of them.

Identifiers

Every id carries a prefix naming the record type and is otherwise opaque (don't parse it further):

vk_ API key, ag_ agent, ad_ agent draft, ado_ draft operation, c_ call, msg_ SMS message, tl_ tool, whd_ webhook delivery, rl_ relay lease, int_ connected integration, inv_ tax document (GET /v1/billing/documents), l_ credit ledger entry, task_ outbound task, item_ task recipient, attempt_ a call attempt on a task item, req_ request id (see Error format above).

Timestamps

Timestamps are unix milliseconds almost everywhere (createdAt, startedAt, boughtAt, issuedAt, taxableAt) - the EXCEPTION is the connected-calendar AND connected-invoice fields: start, end, fetchedAt (calendar) and the timeMin/timeMax parameters are RFC 3339 strings (2026-09-08T10:00:00.000Z), never a number; GET /v1/integrations/{id}/invoices and .../invoices/{externalId} are strings too - fetchedAt is the same RFC 3339 shape, dueDate is a plain date (2026-09-08) straight from Fakturoid/ABRA Flexi, or null when the provider didn't give one.

Pagination - three schemes, plus lists with none

GET /v1/messages, GET /v1/calls and GET /v1/billing/documents take limit + before (a ms timestamp, exclusive) and answer with hasMore/nextBefore - see Pagination above for the details. Connected-calendar events (GET /v1/integrations/{id}/events) use an opaque pageToken/nextPageToken instead - timeMin/timeMax/search need to stay unchanged between pages, pageToken alone doesn't guarantee that. GET /v1/credit/ledger takes only limit (1-200, default 50), no cursor at all - it always starts from the most recent entry. GET /v1/tasks also has no cursor and returns at most the 100 most recent tasks. GET /v1/webhook/deliveries also has no cursor and returns at most the last 50 deliveries (successful, failed and test ones). Connected-invoice search silently caps out too - the first 40 Fakturoid or 50 ABRA Flexi rows, with no cursor to see more; narrow the search instead. Everything else that returns a list (agents, numbers, SMS numbers, tools, API keys, the do-not-call list, voices) returns the full set in one response - there is nothing to page through.

Unknown and Czech-named parameters

An unknown query parameter is silently ignored almost everywhere (so an older client doesn't break on one extra parameter) - the exception is the connected-calendar and connected-invoice endpoints (/v1/integrations/{id}/...), which reject an unknown parameter with 400 validation, because they forward it to the upstream provider and a silently-dropped filter there would look like missing data, not an error; and, for an unrelated reason, GET /v1/credit/ledger and GET /v1/billing/documents, whose query schemas are strict on purpose so a typo in limit/before fails loudly instead of being silently ignored.

A handful of fields intentionally keep a Czech name: the number address flow (GET /v1/numbers/address-options, then POST /v1/numbers/orders - plain POST /v1/numbers only takes e164/region and ignores an address) passes psc, obec, cobce, ulice (only where the address has a street) and cp - the exact field names of the RÚIAN registry (the operator's own address code list) the number is ordered from, so a value round-tripped between the two is never silently mistranslated. GET /v1/calls/{id}/recording?stahnout=1 is the one Czech-named parameter outside that flow (download as an attachment instead of inline). Everything else - identifiers, fields and parameters alike - is English.

Quotas, gathered in one place

Each quota is also mentioned next to its own endpoint above - this is just the summary:

• 60 requests/min per API key (REST and MCP share it, see Rate limits above)
• SMS: 1 every 2 s and 100/day per account, only after the first credit top-up
• SMS sent from an SMS number (fromNumber): additionally 20 messages a day per account in the first 30 days after you buy the number, 50 after that; at most two SMS numbers per account
• Outbound calls (agent, bridge, trial): 10/min and 1000/day per account, at most 2 built-in-agent calls running at once
• Trial call with no number of your own (POST /v1/calls with systemPrompt instead of agentId/from): additionally 3/24h per account AND a shared cap of 30/hour across ALL accounts combined - the shared cap can hit you with no fault of your own.
• POST /v1/agents/{id}/test-call: 3/day per account
• POST /v1/tools/test and .../{id}/test: 10/min per account
• POST /v1/agents/{id}/simulate: 20/hour per account
• POST /v1/webhook/test: 10/hour per account
• GET /v1/changelog: 30/min per IP (no API key)
• Tasks: a running task dials at most ONE recipient per cron tick (*/2 * * * *), and one tick touches at most 20 tasks across ALL accounts combined - so even with credit and an open calling window, calls from one task land roughly two minutes apart, and under load (more than 20 tasks running at once) tasks rotate fairly rather than one finishing before the next starts.

Webhook retries

A failed delivery gets up to 3 attempts, 3 seconds apart, within the same dispatch. For call events (call.completed, call.failed, call.no_answer, call.missed) and for message.received that isn't the end of it: the event stays queued and delivery is retried a few more times over the following minutes, up to 5 rounds total - dedupe by the body's event_id in the rare case it arrives more than once. message.sent and the test event webhook.test have no queue: after a failure it's just logged and not sent again. Check GET /v1/webhook/deliveries (or list_webhook_deliveries) to see progress, including rounds before the final one - attempts there is the sum of attempts across ALL rounds.

Deprecation

v1 has so far only ever added (see Versioning above) - the only exception was version 1.5.1, which stopped returning answeredBy for INBOUND calls (the field never had a meaningful value there; it is unchanged for outbound calls). volai hasn't fully retired a field yet. When it does, the field is marked deprecated: true in GET /openapi.json and the response carries Deprecation/Sunset headers at least 90 days ahead, and an MCP response that touches it gets an entry in warnings (the same field already used today for the AI Act disclosure warning) - removal itself only ever ships as a new major version (v2), never silently inside v1.

Calls vs. conversations - see the paragraph of the same name under Calls below before summing counts.

Credentials (a password, a token, an app-specific password) go only where the user already put them somewhere you can read (an environment variable or a file they named) - never ask for one in conversation, never echo it back; applies today to Apple Calendar and ABRA Flexi (see the calendar and invoice sections below).

What the API can't do

You control the whole phone side through API and MCP - numbers, calls, SMS, agents, webhooks, relay, and the do-not-call list. Your profile, billing address, and company details go through the API too (the Account section above). A few things do stay portal-only, by design:

Going the other way, more than one thing is missing on purpose: releasing a number you bought (DELETE /v1/numbers/{e164}) or an SMS number (DELETE /v1/sms-numbers/{e164}) exists in both the REST API and the portal, but not among the MCP tools - an irreversible action is one misread sentence away from being too risky there. Also missing on purpose: downloading a recording (a binary body, GET /v1/calls/{id}/recording), the detail of a single message or tool (the list_messages/list_tools listings already carry the same fields, just not for one ID at a time), and a dedicated test-call tool - make_call with agentId dials the same call as POST /v1/agents/{id}/test-call, just without its stricter daily cap of 3 calls.

Account

Profile, emergency address, billing details and an API key overview. Creating new API keys (POST /v1/api-keys) is not exposed - a key that mints keys would turn losing one into permanent access. Create a new key in the portal (Access and API section). E-mail notifications (callSummary, lowCredit, reactivation, productUpdates) are READ-only through this interface - writing is portal-only, because lowCredit is the only brake between running out of credit and silently going dark.

curl https://volai.cz/v1/account \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "account": {
    "id": "u_8f2a1c9d3b47",
    "email": "radek@example.com",
    "name": "Radek Klein",
    "locale": "cs",
    "emailVerified": true,
    "createdAt": 1755000000000,
    "companyName": "Ukázková s.r.o.",
    "address": { "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
    "billing": null,
    "notifications": { "callSummary": true, "lowCredit": true, "reactivation": true, "productUpdates": true, "weeklySummary": true }
  }
}

curl -X PATCH https://volai.cz/v1/account \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locale":"en"}'

{
  "account": {
    "id": "u_8f2a1c9d3b47",
    "email": "radek@example.com",
    "name": "Radek Klein",
    "locale": "en",
    "emailVerified": true,
    "createdAt": 1755000000000,
    "companyName": "Ukázková s.r.o.",
    "address": { "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
    "billing": null,
    "notifications": { "callSummary": true, "lowCredit": true, "reactivation": true, "productUpdates": true, "weeklySummary": true }
  }
}

curl -X PUT https://volai.cz/v1/account/billing \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company":"Ukázková s.r.o.","dic":"SK9999999999","address":{"street":"Na Zámku 636","city":"Nehvizdy","zip":"250 81"}}'

{
  "billing": {
    "company": "Ukázková s.r.o.",
    "ico": null,
    "dic": "SK9999999999",
    "dicCountry": "SK",
    "dicVerified": true,
    "dicName": "Ukázková s.r.o."
  },
  "address": { "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
  "vies": { "dic": "SK9999999999", "country": "Slovakia", "name": "Ukázková s.r.o." }
}

curl https://volai.cz/v1/api-keys \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "apiKeys": [
    {
      "id": "3f9a2c8e1b04",
      "label": "Production integration",
      "prefix": "vk_8h2j4kx",
      "createdAt": 1750000000000,
      "lastUsedAt": 1757280000000
    }
  ]
}

curl -X DELETE https://volai.cz/v1/api-keys/3f9a2c8e1b04 \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "revoked": true
}

Credit

balanceHal and every rate in this API are exclusive of VAT - volai is VAT-registered, but VAT is only applied when you top up credit by card in the portal (see the /en/pricing page), the API itself doesn't factor it in. A full walkthrough with flow examples is at /en/docs/credit.

curl https://volai.cz/v1/balance \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "balanceHal": 8730,
  "balanceCzk": 87.30,
  "currency": "CZK",
  "runway": { "dailyAverageHal": 2910, "runwayDays": 3 },
  "notice": { "kind": "runway", "days": 3 }
}

curl "https://volai.cz/v1/credit/ledger?limit=3" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "ledger": [
    { "id": "l_9f2a1c8e", "ts": 1757280000000, "type": "call_out", "amountHal": -420, "grossHal": null, "description": "Outbound call" },
    { "id": "l_7c1e9a2f", "ts": 1757193600000, "type": "number_fee", "amountHal": -9900, "grossHal": null, "description": "Monthly number fee for +420601234567" },
    { "id": "l_3b7e1c9a", "ts": 1757107200000, "type": "topup", "amountHal": 50000, "grossHal": 60500, "description": "Card top-up" }
  ]
}

curl -X POST https://volai.cz/v1/credit/topup \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: topup-2026-09-08-01" \
  -d '{"amountCzk": 500}'

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl https://volai.cz/v1/credit/auto-topup \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "autoTopup": {
    "enabled": true,
    "thresholdHal": 10000,
    "amountHal": 50000,
    "card": { "brand": "visa", "last4": "4242" },
    "spentThisMonthHal": 50000,
    "monthlyCapHal": 1000000,
    "disabledReason": null
  }
}

curl -X PATCH https://volai.cz/v1/credit/auto-topup \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"thresholdHal": 20000}'

{
  "autoTopup": {
    "enabled": true,
    "thresholdHal": 20000,
    "amountHal": 50000,
    "card": { "brand": "visa", "last4": "4242" },
    "spentThisMonthHal": 50000,
    "monthlyCapHal": 1000000,
    "disabledReason": null
  }
}

curl -X POST https://volai.cz/v1/credit/auto-topup/setup \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: autotopup-setup-2026-09-08-01" \
  -d '{"thresholdHal": 10000, "amountHal": 50000}'

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl -X POST https://volai.cz/v1/credit/auto-topup/card \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4"
}

curl -X DELETE https://volai.cz/v1/credit/auto-topup/card \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "removed": true
}

curl "https://volai.cz/v1/billing/documents?limit=2" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "documents": [
    {
      "id": "inv_4kX9mQ2pRtLz",
      "number": "VF2026000042",
      "issuedAt": 1757280000000,
      "taxableAt": 1757280000000,
      "netHal": 50000,
      "vatHal": 10500,
      "grossHal": 60500,
      "vatRatePercent": 21,
      "reverseCharge": false,
      "kind": "invoice",
      "description": "Prepaid credit for volai telecommunications services",
      "customer": { "name": "Radek Klein", "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
      "paymentRef": "pi_3PQr7s2eZvKYlo2C1a2b3c4d",
      "pdfUrl": "https://volai.cz/v1/billing/documents/inv_4kX9mQ2pRtLz/pdf"
    }
  ],
  "hasMore": false,
  "nextBefore": null
}

curl https://volai.cz/v1/billing/documents/inv_4kX9mQ2pRtLz \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "document": {
    "id": "inv_4kX9mQ2pRtLz",
    "number": "VF2026000042",
    "issuedAt": 1757280000000,
    "taxableAt": 1757280000000,
    "netHal": 50000,
    "vatHal": 10500,
    "grossHal": 60500,
    "vatRatePercent": 21,
    "reverseCharge": false,
    "kind": "invoice",
    "description": "Prepaid credit for volai telecommunications services",
    "customer": { "name": "Radek Klein", "street": "Na Zámku 636", "city": "Nehvizdy", "zip": "250 81" },
    "paymentRef": "pi_3PQr7s2eZvKYlo2C1a2b3c4d",
    "pdfUrl": "https://volai.cz/v1/billing/documents/inv_4kX9mQ2pRtLz/pdf"
  }
}

curl https://volai.cz/v1/billing/documents/inv_4kX9mQ2pRtLz/pdf \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -o invoice.pdf

Tasks

A task dials a list of recipients with one agent, following rules set up front (budget, calling window, number of attempts) - nothing gets dialed until you start it yourself (POST .../start). A full guide with the CSV import, statuses and global throughput is at /en/docs/tasks.

curl https://volai.cz/v1/tasks \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "tasks": [
    {
      "id": "task_9f3a2c1d",
      "name": "Payment reminder - September",
      "agentId": "ag_4e91a2f0",
      "taskType": "custom",
      "source": "manual",
      "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
      "maxAttempts": 2,
      "maxDurationSecs": 120,
      "budgetHal": 50000,
      "reservedBudgetHal": 0,
      "spentHal": 0,
      "status": "draft",
      "revision": 0,
      "createdAt": 1757280000000,
      "updatedAt": 1757280000000,
      "items": [
        { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
      ]
    }
  ]
}

curl -X POST https://volai.cz/v1/tasks \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: task-2026-09-08-01" \
  -d '{
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "source": "manual",
    "maxAttempts": 2,
    "budgetHal": 50000,
    "recipients": [
      { "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" } }
    ]
  }'

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 50000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "draft",
    "revision": 0,
    "createdAt": 1757280000000,
    "updatedAt": 1757280000000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
    ]
  }
}

curl https://volai.cz/v1/tasks/task_9f3a2c1d \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 50000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "draft",
    "revision": 0,
    "createdAt": 1757280000000,
    "updatedAt": 1757280000000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
    ],
    "issues": []
  }
}

curl -X PATCH https://volai.cz/v1/tasks/task_9f3a2c1d \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision": 0, "budgetHal": 80000}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "draft",
    "revision": 1,
    "createdAt": 1757280000000,
    "updatedAt": 1757280060000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/start \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: task-start-2026-09-08-01" \
  -d '{"revision": 1}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "running",
    "revision": 2,
    "createdAt": 1757280000000,
    "updatedAt": 1757280120000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [] }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/pause \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision": 2}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "status": "paused",
    "revision": 3,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 684,
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "createdAt": 1757280000000,
    "updatedAt": 1757280180000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "completed", "attempts": [{ "id": "attempt_5d4c3b", "startedAt": 1757280100000, "finishedAt": 1757280160000, "providerCallId": "c_7a2b9c1d", "outcome": "completed", "costHal": 684 }], "actualCostHal": 684 }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/items/item_1a2b3c/resolve \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "retry", "revision": 5}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 80000,
    "reservedBudgetHal": 2400,
    "spentHal": 0,
    "status": "needs_attention",
    "revision": 6,
    "createdAt": 1757280000000,
    "updatedAt": 1757280240000,
    "reviewReason": "billing_unknown",
    "items": [
      {
        "id": "item_1a2b3c",
        "phone": "+420777123456",
        "variables": { "jmeno": "Jana Novakova" },
        "paymentStatus": "not_applicable",
        "status": "pending",
        "attempts": [
          { "id": "attempt_7c2d", "startedAt": 1757280180000, "finishedAt": 1757280230000, "providerCallId": "c_late_price", "outcome": "completed" }
        ],
        "reviewReason": "billing_unknown",
        "providerCallId": "c_late_price",
        "estimatedCostHal": 2400,
        "reservedCostHal": 2400
      }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/reconcile \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "task": {
    "id": "task_9f3a2c1d",
    "status": "completed",
    "revision": 3,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 684,
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "createdAt": 1757280000000,
    "updatedAt": 1757280240000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "completed", "attempts": [{ "id": "attempt_5d4c3b", "startedAt": 1757280100000, "finishedAt": 1757280160000, "providerCallId": "c_7a2b9c1d", "outcome": "completed", "costHal": 684 }], "actualCostHal": 684 }
    ]
  }
}

curl -X POST https://volai.cz/v1/tasks/task_9f3a2c1d/process \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: task-process-2026-10-08-tick-001" \
  -d '{"revision": 2}'

{
  "status": "idle",
  "task": {
    "id": "task_9f3a2c1d",
    "name": "Payment reminder - September",
    "agentId": "ag_4e91a2f0",
    "taskType": "custom",
    "source": "manual",
    "callingWindow": { "timezone": "Europe/Prague", "start": "09:00", "end": "18:00", "days": [1, 2, 3, 4, 5] },
    "maxAttempts": 2,
    "maxDurationSecs": 120,
    "budgetHal": 80000,
    "reservedBudgetHal": 0,
    "spentHal": 0,
    "status": "running",
    "revision": 2,
    "createdAt": 1757280000000,
    "updatedAt": 1757280120000,
    "items": [
      { "id": "item_1a2b3c", "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "paymentStatus": "not_applicable", "status": "pending", "attempts": [], "nextAttemptAt": 1757280180000 }
    ]
  }
}

curl -X DELETE "https://volai.cz/v1/tasks/task_9f3a2c1d?revision=3" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "deleted": true
}

curl -X POST https://volai.cz/v1/tasks/csv-preview \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"csv": "phone,jmeno\n+420777123456,Jana Novakova\nneplatne,Petr Svoboda\n"}'

{
  "headers": ["phone", "jmeno"],
  "delimiter": ",",
  "rows": [
    { "line": 2, "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" }, "errors": [] },
    { "line": 3, "variables": { "jmeno": "Petr Svoboda" }, "errors": [{ "field": "phone", "message": "Invalid phone number", "row": 3 }] }
  ],
  "validRows": [
    { "phone": "+420777123456", "variables": { "jmeno": "Jana Novakova" } }
  ],
  "errors": [{ "field": "phone", "message": "Invalid phone number", "row": 3 }]
}

Numbers

curl "https://volai.cz/v1/numbers/+420601234567/callback-routing" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{"callbackRouting":{"agentIds":["ag_campaign"],"lookbackSecs":604800}}

curl -X PUT "https://volai.cz/v1/numbers/+420601234567/callback-routing" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentIds":["ag_campaign"],"lookbackSecs":604800}'

{"callbackRouting":{"agentIds":["ag_campaign"],"lookbackSecs":604800},"engineSyncRequired":true}

curl https://volai.cz/v1/numbers \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "numbers": [
    {
      "e164": "+420601234567",
      "routing": { "mode": "agent", "agentId": "ag_kx91fa2b", "hasSipPassword": false, "sipTarget": "engine" },
      "monthlyFeeHal": 2500,
      "boughtAt": 1756111640000,
      "region": "objednavka",
      "regionLabel": "Czech number",
      "billingMonths": 1
    }
  ]
}

curl "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "number": {
    "e164": "+420601234567",
    "routing": { "mode": "agent", "agentId": "ag_kx91fa2b", "hasSipPassword": false, "sipTarget": "engine" },
    "monthlyFeeHal": 2500,
    "boughtAt": 1756111640000,
    "region": "objednavka",
    "regionLabel": "Czech number",
    "billingMonths": 1
  }
}

curl -X POST https://volai.cz/v1/numbers \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "number": {
    "e164": "+420266266647",
    "routing": { "mode": "none", "hasSipPassword": false },
    "monthlyFeeHal": 2500,
    "boughtAt": 1756111640000,
    "region": "praha",
    "regionLabel": "Prague",
    "billingMonths": 1
  }
}

curl https://volai.cz/v1/numbers/waitlist \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "offers": [
    { "offerId": "praha", "label": "Prague", "joined": false, "available": true },
    { "offerId": "brno", "label": "Brno", "joined": true, "available": false },
    { "offerId": "internet", "label": "Internet number", "joined": false, "available": true },
    { "offerId": "bratislava", "label": "Bratislava", "joined": false, "available": true }
  ]
}

curl -X POST https://volai.cz/v1/numbers/waitlist \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offerId": "brno"}'

{
  "joined": true
}

curl -X DELETE https://volai.cz/v1/numbers/waitlist/brno \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "left": true
}

curl "https://volai.cz/v1/numbers/available?region=brno" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "region": "brno",
  "numbers": ["+420510510129", "+420510510132"],
  "regions": [
    {
      "id": "praha",
      "label": "Prague",
      "description": "A landline with a Prague area code.",
      "numbers": ["+420266266643", "+420266266645"]
    },
    {
      "id": "brno",
      "label": "Brno",
      "description": "A landline with a Brno area code.",
      "numbers": ["+420510510129", "+420510510132"]
    },
    {
      "id": "internet",
      "label": "Internet number",
      "description": "Area code 910, not tied to any region - works from anywhere.",
      "numbers": ["+420910084099"]
    },
    {
      "id": "bratislava",
      "label": "Bratislava",
      "description": "A Slovak number with the Bratislava area code +421 2. Billed three months upfront.",
      "numbers": ["+421222205798"]
    }
  ]
}

curl "https://volai.cz/v1/numbers/address-options?psc=70200&obec=554821&cobce=413950" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "obce": [{ "value": "554821", "label": "Ostrava" }],
  "casti": [{ "value": "413950", "label": "Moravská Ostrava" }],
  "ulice": [{ "value": "353710", "label": "28. října" }],
  "cp": [],
  "recap": null
}

curl -G https://volai.cz/v1/numbers/address-options \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  --data-urlencode "query=Nádražní 100, 702 00 Ostrava"

{
  "obce": [],
  "casti": [],
  "ulice": [],
  "cp": [],
  "recap": "28. října 102/1, Ostrava, 70200",
  "selection": {
    "psc": "70200",
    "obec": "554821",
    "cobce": "413950",
    "ulice": "353710",
    "cp": "3180026"
  }
}

{
  "obce": [
    { "value": "554821", "label": "Ostrava" },
    { "value": "554813", "label": "Fulnek" }
  ],
  "casti": [],
  "ulice": [],
  "cp": [],
  "recap": null,
  "selection": { "psc": "70200", "obec": "", "cobce": "", "ulice": "", "cp": "" },
  "ambiguousLevel": "obec",
  "message": "The given address is ambiguous - choose the municipality (obec) from the options. Repeat the query WITHOUT query and with the step parameters: psc=70200, obec=<value from the options>."
}

curl -X POST https://volai.cz/v1/numbers/orders \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"psc":"70200","obec":"554821","cobce":"413950","ulice":"353710","cp":"3180026"}'

{
  "order": {
    "id": "Xa3Kd9pQmR2v",
    "status": "pending",
    "address": "70200",
    "createdAt": 1756111640000,
    "updatedAt": 1756111640000
  }
}

curl https://volai.cz/v1/numbers/orders \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "orders": [
    {
      "id": "Xa3Kd9pQmR2v",
      "status": "done",
      "address": "28. října 102/1, Ostrava, 70200",
      "e164": "+420596123456",
      "createdAt": 1756111640000,
      "updatedAt": 1756118840000
    }
  ]
}

curl -X POST https://volai.cz/v1/numbers/orders/Xa3Kd9pQmR2v/cancel \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "order": {
    "id": "Xa3Kd9pQmR2v",
    "status": "cancelled",
    "address": "28. října 102/1, Ostrava, 70200",
    "createdAt": 1756111640000,
    "updatedAt": 1756112240000
  }
}

curl -X DELETE "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "released": true
}

curl -X PATCH "https://volai.cz/v1/numbers/+420601234567" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"routing": {"mode": "agent", "agentId": "ag_kx91fa2b"}}'

{
  "number": {
    "e164": "+420601234567",
    "routing": { "mode": "agent", "agentId": "ag_kx91fa2b", "hasSipPassword": false, "sipTarget": "engine" },
    "monthlyFeeHal": 2500,
    "boughtAt": 1756111640000,
    "region": "objednavka",
    "regionLabel": "Czech number",
    "billingMonths": 1
  }
}

curl "https://volai.cz/v1/numbers/+420601234567/sip" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "server": "sip.volai.cz",
  "username": "123456",
  "password": "a1b2c3d4e5f6",
  "outboundTrunkAddress": "sip.volai.cz",
  "port": 5060,
  "transport": "tcp",
  "inboundSignallingCidrs": ["81.31.45.0/24"]
}

curl "https://volai.cz/v1/numbers/+420601234567/sip/status" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "target": { "kind": "own_line", "host": null },
  "registration": { "registered": true },
  "lastInbound": {
    "at": 1756118900000,
    "status": "completed",
    "from": "+420777123456",
    "recent": true
  }
}

Messages

curl "https://volai.cz/v1/messages?limit=20&direction=all" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "messages": [
    {
      "id": "msg_5b7e0d93",
      "to": "+420777123456",
      "from": "+420770112233",
      "body": "Confirmed, see you on Friday at 10:00. - My App",
      "status": "sent",
      "failReason": null,
      "priceHal": 190,
      "segments": 1,
      "createdAt": 1756112200000,
      "source": "api",
      "direction": "out",
      "smsNumber": "+420770112233",
      "deliveryStatus": "delivered"
    },
    {
      "id": "msg_3d9b5e71",
      "to": "+420770112233",
      "from": "+420777123456",
      "body": "Thanks, I will come on Friday at 10:00.",
      "status": "received",
      "failReason": null,
      "priceHal": 0,
      "segments": 1,
      "createdAt": 1756111900000,
      "source": "inbound",
      "direction": "in",
      "smsNumber": "+420770112233",
      "deliveryStatus": null
    },
    {
      "id": "msg_7c1f9a2e",
      "to": "+420777123456",
      "from": "volai",
      "body": "Hello from volai! - My App",
      "status": "sent",
      "failReason": null,
      "priceHal": 136,
      "segments": 1,
      "createdAt": 1756111500000,
      "source": "api",
      "direction": "out",
      "smsNumber": null,
      "deliveryStatus": null
    }
  ],
  "hasMore": false,
  "nextBefore": null
}

curl -X POST "https://volai.cz/v1/messages" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_MESSAGES_ID" \
  -d '{"to":"+420777123456","body":"Hello from volai! - My App"}'

{
  "id": "msg_7c1f9a2e",
  "status": "sent",
  "priceHal": 136,
  "segments": 1
}

A message's status: pending (stored, still sending), sent (the carrier accepted the message for sending, including queued messages; this is not a delivery receipt), failed (the carrier rejected it, for a message sent from an SMS number possibly only afterwards - not billed, any credit already charged is refunded, priceHal 0), received (a message received on your SMS number, always with direction: "in" and priceHal 0) and unknown (the carrier did not confirm acceptance, typically because its response timed out) - it's still billed at full price, since the message may have gone through. For a message sent from an SMS number, unknown can still change on its own: to sent with a deliveryStatus once the carrier confirms the message, or to failed with the credit refunded if it rejects it. If you get unknown, please don't resend it blindly - contact support and we'll refund any duplicate charge.

For status: "failed" you also get failReason: unsupported_characters (an emoji or character the network cannot deliver), unsupported_recipient (the network does not accept the number), forbidden_sender and low_balance (an error on our side), gateway_failed (the operator's gateway), network_rejected (some other rejection), opted_out (the recipient replied STOP to your SMS number). For other statuses it is null.

deliveryStatus (delivered or undelivered) is the carrier's delivery report and exists only for messages sent from your SMS number. It is null for messages sent under the shared name SMSinfo, which has no delivery reports, and for received messages. sent still only means the carrier accepted the message and does not prove delivery. A message with undelivered is still billed, because the carrier accepted it. If the carrier later reports a failure, the message's status changes to failed, priceHal drops to 0 and the credit for it is refunded. The delivery report arrives as soon as the carrier reports it; if the status notification does not arrive, a regular check every 15 minutes fills it in. If the carrier never reports it, it stays null.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "fromNumber": "+420770112233", "body": "Confirmed, see you on Friday at 10:00. - My App"}'

{
  "id": "msg_5b7e0d93",
  "status": "sent",
  "priceHal": 190,
  "segments": 1
}

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "body": "Příliš žluťoučký kůň úpěl ďábelské ódy - a tahle věta má přes sedmdesát znaků, takže spadne do druhého segmentu."}'

{
  "id": "msg_9a3f1c7d",
  "status": "sent",
  "priceHal": 272,
  "segments": 2
}

curl https://volai.cz/v1/messages/msg_7c1f9a2e \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "message": {
    "id": "msg_7c1f9a2e",
    "to": "+420777123456",
    "from": "volai",
    "body": "Hello from volai! - My App",
    "status": "sent",
    "failReason": null,
    "priceHal": 136,
    "segments": 1,
    "createdAt": 1756111500000,
    "source": "api",
    "direction": "out",
    "smsNumber": null,
    "deliveryStatus": null
  }
}

SMS numbers

curl https://volai.cz/v1/sms-numbers \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "smsNumbers": [
    {
      "number": "+420770112233",
      "status": "active",
      "createdAt": 1756111640000,
      "monthlyFeeHal": 39000,
      "nextChargeAt": 1758703640000,
      "dailySendLimit": 20,
      "dailySendRemaining": 17,
      "dailySendResetsAt": 1756198040000
    }
  ]
}

curl -X POST "https://volai.cz/v1/sms-numbers" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_SMS_NUMBERS_ID"

{
  "smsNumber": {
    "number": "+420770112233",
    "status": "active",
    "createdAt": 1756111640000,
    "monthlyFeeHal": 39000,
    "nextChargeAt": 1758703640000,
    "dailySendLimit": 20,
    "dailySendRemaining": 20,
    "dailySendResetsAt": null
  }
}

curl -X DELETE "https://volai.cz/v1/sms-numbers/+420770112233" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "released": true
}

Calls

curl "https://volai.cz/v1/calls?limit=20" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "calls": [
    {
      "id": "c_8f2ac1d4",
      "direction": "in",
      "from": "+420777123456",
      "to": "+420601234567",
      "status": "completed",
      "startedAt": 1756111400000,
      "durationSecs": 47,
      "priceHal": 236,
      "agentId": "ag_kx91fa2b",
      "note": null,
      "flag": null,
      "handledAt": null,
      "rating": null,
      "goal": null,
      "hasConversation": true,
      "source": "inbound",
      "kind": "inbound",
      "endReason": "completed",
      "hasRecording": true,
      "data": {
        "name": "Jane Smith",
        "coffee_count": 2,
        "urgency": "normal"
      }
    }
  ],
  "hasMore": false,
  "nextBefore": null
}

curl -X POST "https://volai.cz/v1/calls" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_CALLS_ID" \
  -d '{"to":"+420777123456","agentId":"ag_kx91fa2b","variables":{"jmeno_zakaznika":"Jana","cislo_objednavky":"A-42"},"ringingTimeoutSecs":30}'

{
  "id": "c_9d4e2b7f",
  "status": "initiated"
}

curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "from": "+420601234567"}'

curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+420777123456",
    "systemPrompt": "You are the front desk at cafe Nula. You take pickup orders and keep it brief and friendly.",
    "firstMessage": "Hello, this is the volai trial agent, how can I help you?"
  }'

{
  "id": "c_2f7a91mn",
  "status": "initiated",
  "trial": true,
  "from": "+420266266641"
}

curl 'https://volai.cz/v1/calls/active?agentId=ag_example' -H 'Authorization: Bearer vk_YOUR_KEY'

{
  "data": {
    "agentId": "ag_example",
    "complete": true,
    "checkedAt": "2026-10-09T17:59:00.000Z",
    "enginesChecked": 2,
    "outboundCount": 0,
    "inboundCount": 0,
    "unresolvedOutboundCount": 0,
    "outbound": []
  }
}

curl -X POST https://volai.cz/v1/calls/c_example/hangup -H 'Authorization: Bearer vk_YOUR_KEY' -H 'Content-Type: application/json' -d '{"expectedAgentId":"ag_example","expectedTaskId":"task_example","expectedItemId":"item_example","expectedPhoneSha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}'

{
  "data": {
    "callId": "c_example",
    "outcome": "hung_up",
    "endConfirmed": true
  }
}

curl https://volai.cz/v1/calls/c_8f2ac1d4 \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "call": {
    "id": "c_8f2ac1d4",
    "direction": "in",
    "from": "+420777123456",
    "to": "+420601234567",
    "status": "completed",
    "startedAt": 1756111400000,
    "durationSecs": 47,
    "priceHal": 236,
    "agentId": "ag_kx91fa2b",
    "note": null,
    "flag": null,
    "handledAt": null,
    "rating": null,
    "goal": null,
    "hasConversation": true,
    "source": "inbound",
    "kind": "inbound",
    "endReason": "completed",
    "hasRecording": true,
    "data": {
      "name": "Jane Smith",
      "coffee_count": 2,
      "urgency": "normal"
    },
    "transcript": [
      { "role": "agent", "message": "Hi, this is cafe Nula, how can I help you?", "timeInCallSecs": 0 },
      { "role": "caller", "message": "I would like to order two lattes to go.", "timeInCallSecs": 4 },
      { "role": "agent", "message": "Sure, two lattes for pickup, they will be ready in fifteen minutes.", "timeInCallSecs": 9 }
    ],
    "summary": "The caller ordered two lattes to go, pickup in 15 minutes."
  }
}

curl -X GET "https://volai.cz/v1/calls/c_9d4e2b7f?waitSecs=30" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "call": {
    "id": "c_9d4e2b7f",
    "direction": "out",
    "from": "+420601234567",
    "to": "+420777123456",
    "status": "completed",
    "startedAt": 1756111400000,
    "durationSecs": 47,
    "priceHal": 269,
    "agentId": "ag_kx91fa2b",
    "note": null,
    "flag": null,
    "handledAt": null,
    "rating": null,
    "goal": null,
    "hasConversation": true,
    "source": "api",
    "kind": "agent",
    "endReason": "completed",
    "hasRecording": true,
    "answeredBy": "human"
  }
}

{
  "call": {
    "id": "c_9d4e2b7f",
    "direction": "out",
    "from": "+420601234567",
    "to": "+420777123456",
    "status": "ringing",
    "startedAt": 1756111400000,
    "agentId": "ag_kx91fa2b",
    "note": null,
    "flag": null,
    "handledAt": null,
    "rating": null,
    "goal": null,
    "hasConversation": null,
    "source": "api"
  },
  "stillRunning": true
}

curl https://volai.cz/v1/calls/c_8f2ac1d4/recording \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -OJ

curl -X PATCH https://volai.cz/v1/calls/c_8f2ac1d4 \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Volal kvůli reklamaci, přeposlat na podporu.", "flag": {"reason": "Agent nerozuměl dotazu na fakturu."}}'

{
  "call": {
    "id": "c_8f2ac1d4",
    "direction": "in",
    "from": "+420777123456",
    "to": "+420601234567",
    "status": "completed",
    "startedAt": 1756111400000,
    "durationSecs": 47,
    "priceHal": 236,
    "agentId": "ag_kx91fa2b",
    "source": "inbound",
    "kind": "inbound",
    "endReason": "completed",
    "hasRecording": true,
    "data": { "name": "Jane Smith" },
    "note": "Volal kvůli reklamaci, přeposlat na podporu.",
    "flag": { "reason": "Agent nerozuměl dotazu na fakturu.", "flaggedAt": 1756111460000 },
    "handledAt": null,
    "rating": null,
    "goal": { "result": "failure", "rationale": "The caller ordered two lattes to go, pickup in 15 minutes.", "reason": null },
    "hasConversation": true
  }
}

Call status: the status field

status is the only field that changes over time on a call. It can still move during the first five minutes after the call starts; after that it's final - four of these states are terminal.

Call type: the kind field

kind says how a call came to exist - and therefore how it's billed. It's the only field that lets you tell a bring-your-own (BYO) agent's call apart from a built-in agent's call on an invoice, since relay legs don't carry the agent surcharge.

Why a call ended: the endReason field

We add endReason to every closed call. Watch out: a call blocked over unpaid debt or by a manual suspension has status completed, but endReason is credit_blocked or suspended respectively and the price is 0 - status alone won't tell it apart from a call that actually went through. The same goes for a call with an automated caller on the other end repeating the same message (caller_loop): it has status completed, but if it lasted up to five minutes its price is 0. The three "unanswered" variants are deliberately distinct, not one shared state.

Agents

curl https://volai.cz/v1/agents \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "agents": [
    {
      "id": "ag_pw7q2vnd",
      "name": "Front desk",
      "language": "en",
      "systemPrompt": "You are the front desk at cafe Nula. You take pickup orders...",
      "firstMessage": "Hi, this is cafe Nula, how can I help you?",
      "voiceId": "7JbZPqJGWUfXXBim0T8U",
      "provider": "elevenlabs",
      "createdAt": 1756111000000,
      "status": "active",
      "toolIds": ["tl_5c2a91f4"],
      "dataFields": [
        {
          "key": "name",
          "type": "string",
          "description": "The caller's name, as they stated it."
        }
      ],
      "recordCalls": true,
      "goal": null,
      "knowledge": null,
      "notifyEmail": true,
      "silencePromptSecs": 10,
      "laughter": "auto",
      "missedCallSms": { "enabled": false },
      "suspended": false
    },
    {
      "id": "ag_kx91fa2b",
      "name": "Front desk",
      "language": "en",
      "systemPrompt": "You are the front desk at cafe Nula. You take pickup orders...",
      "firstMessage": "Hi, this is cafe Nula, how can I help you?",
      "voiceId": "milena",
      "provider": "engine",
      "numberE164": "+420601234567",
      "createdAt": 1756111000000,
      "status": "active",
      "toolIds": ["tl_5c2a91f4"],
      "transferTo": "+420777123456",
      "transferCondition": "The caller explicitly asks to be connected with a human.",
      "dataFields": [
        {
          "key": "name",
          "type": "string",
          "description": "The caller's name, as they stated it."
        },
        {
          "key": "urgency",
          "type": "string",
          "description": "How urgent the request was.",
          "enumValues": ["low","normal","high"]
        }
      ],
      "recordCalls": true,
      "goal": null,
      "knowledge": null,
      "notifyEmail": true,
      "silencePromptSecs": 10,
      "laughter": "auto",
      "missedCallSms": { "enabled": false },
      "suspended": false
    }
  ]
}

curl -X POST "https://volai.cz/v1/agents" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_AGENTS_ID" \
  -d '{"name":"Front desk","systemPrompt":"You are the front desk at cafe Nula. You take pickup orders and answer questions about opening hours. Never make up prices you do not know. End the call by summarising the order.","firstMessage":"Hi, this is cafe Nula, how can I help you?","language":"en","numberE164":"+420601234567","toolIds":["tl_5c2a91f4"],"transferTo":"+420777123456","transferCondition":"The caller wants to speak with staff, or has a complaint.","dataFields":[{"key":"name","type":"string","description":"The caller'\''s name, as they stated it."},{"key":"coffee_count","type":"number","description":"How many coffees the caller ordered."}],"recordCalls":true}'

{
  "id": "ag_kx91fa2b"
}

curl https://volai.cz/v1/agents/ag_kx91fa2b \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "agent": {
    "id": "ag_kx91fa2b",
    "name": "Front desk",
    "language": "en",
    "systemPrompt": "You are the front desk at cafe Nula. You take pickup orders...",
    "firstMessage": "Hi, this is cafe Nula, how can I help you?",
    "voiceId": "milena",
    "provider": "engine",
    "numberE164": "+420601234567",
    "createdAt": 1756111000000,
    "status": "active",
    "toolIds": ["tl_5c2a91f4"],
    "transferTo": "+420777123456",
    "transferCondition": "The caller explicitly asks to be connected with a human.",
    "dataFields": [
      {
        "key": "name",
        "type": "string",
        "description": "The caller's name, as they stated it."
      },
      {
        "key": "urgency",
        "type": "string",
        "description": "How urgent the request was.",
        "enumValues": ["low","normal","high"]
      }
    ],
    "recordCalls": true,
    "goal": null,
    "knowledge": null,
    "notifyEmail": true,
    "silencePromptSecs": 10,
    "laughter": "auto",
    "missedCallSms": { "enabled": false },
    "suspended": false,
    "laughterEffective": {
      "active": true,
      "reason": "ok",
      "sensitiveCategory": null
    }
  }
}

curl https://volai.cz/v1/agents/ag_example/call-hold -H 'Authorization: Bearer vk_YOUR_KEY'

{
  "agentId": "ag_example",
  "held": false,
  "hold": null
}

curl https://volai.cz/v1/agents/ag_example/call-hold -X POST -H 'Authorization: Bearer vk_YOUR_KEY' -H 'Content-Type: application/json' -d '{"reason":"budget_limit","operationId":"budget-stop-001"}'

{
  "agentId": "ag_example",
  "held": true,
  "hold": {
    "agentId": "ag_example",
    "reason": "budget_limit",
    "operationId": "budget-stop-001",
    "fingerprint": "14e5bfb3f57897b30d172ef4ba861b2a27e7beb1de278a94b47bc0f14c614f4c",
    "createdAt": "2026-10-08T12:00:00.000Z"
  }
}

curl -X PATCH https://volai.cz/v1/agents/ag_kx91fa2b \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstMessage": "Hi, cafe Nula, what can I get you?"}'

{
  "agent": {
    "id": "ag_kx91fa2b",
    "name": "Front desk",
    "language": "en",
    "systemPrompt": "You are the front desk at cafe Nula. You take pickup orders...",
    "firstMessage": "Hi, cafe Nula, what can I get you?",
    "voiceId": "milena",
    "provider": "engine",
    "numberE164": "+420601234567",
    "createdAt": 1756111000000,
    "status": "active",
    "toolIds": ["tl_5c2a91f4"],
    "transferTo": "+420777123456",
    "transferCondition": "The caller explicitly asks to be connected with a human.",
    "recordCalls": true,
    "goal": null,
    "knowledge": null,
    "notifyEmail": true,
    "silencePromptSecs": 10,
    "laughter": "auto",
    "missedCallSms": { "enabled": false },
    "suspended": false
  }
}

curl -X DELETE https://volai.cz/v1/agents/ag_kx91fa2b \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "deleted": true
}

The POST /v1/agents, PATCH /v1/agents/{id}, POST /v1/agents/{id}/draft/publish and POST /v1/agents/{id}/draft/rollback responses may carry an optional warnings field. Several codes concern the first line: first_message_no_ai_disclosure when the agent's saved first line doesn't disclose it's a digital assistant (EU AI Act, Article 50), and first_message_too_long when the estimated spoken duration of what the caller actually hears (the first line plus the recording-notice sentence, when recordCalls is on) is over 7 seconds (about 2.53 words per second; digits always, and all-caps abbreviations up to four characters, count per character). An unchanged default first line never triggers this code, only one the customer has edited. Callers who interrupt the agent most often do so within one second of audible speech. An agent with phases (the workflow field, see the Call phases (workflow) section below) adds ten more codes to the same field - dead_end, empty_node, entry_phrase_never_spoken, missing_enter_phrase, short_condition, condition_about_agent, base_prompt_long, workflow_not_synced_to_provider, workflow_node_tool_not_synced and workflow_node_tool_missing (a node references a tool that is no longer on the account - it was deleted; the phase has to be saved without it) - and typically carries them even when the first line is fine (the Reception template returns three). A warning that belongs to one specific phase or transition also carries nodeId, or edgeId. None of the codes block saving - they just flag it. The field is absent from the response only when there's nothing to flag. Rolling a draft back to an earlier revision (draft/rollback) returns warnings just like publishing does, because it also writes the first line to the live agent. Publishing and rollback only (not POST/PATCH /v1/agents) can also return number_changed_by_publish in the same field, with from/to values (E.164, or null for no number), when the republish actually changes the live agent's phone number - it doesn't block publishing either. A separate code, calendar_pending_engine_switch, appears when the agent has calendar (calendar-based appointments) configured but runs on ElevenLabs - the settings are saved and start working once the agent moves to volai's own engine, which turning the calendar on triggers by itself. An agent with a phone number attached (numberE164) whose instructions (systemPrompt or firstMessage) use a {{variable}} outside the set an inbound call actually supplies (caller_number, called_number, attempt_id, volai_blocked, volai_block_reason, trial_prompt, trial_first_message and seven system__* variables) gets prompt_variables_unavailable_inbound - on an inbound call that variable is replaced with empty text. When removing every {{...}} block from a non-empty first line leaves no letter or digit in it outside the variables, it gets first_message_empty. A separate code, agent_misuse_suspected, appears when the agent's configuration (for the responses above) contains wording that may come across as impersonating an authority or another institution, or as a request for sensitive information - see the volai terms, Section 10. The same code in the same shape also comes back in the optional warnings field of PUT /v1/agents/{id}/draft and POST /v1/agents/{id}/simulate (the draft), POST /v1/calls (the trial call prompt or variables), POST /v1/tasks and PATCH /v1/tasks/{id} (the task name and recipient variables) and POST /v1/tools and PATCH /v1/tools/{id} (the tool's description and its parameters). It never blocks saving or sending - it's only a warning. Only POST /v1/agents can also return elevenlabs_by_explicit_choice, when the request sent useForOutboundTasks: false for a language that the deployment would otherwise start on volai's own voice engine (today cs and sk), so the agent stayed on ElevenLabs - without the engine voices and without the features that run only on the engine. The agent is still created, the warning only flags it; if you only wanted an agent for incoming calls, omit the field.

{
  "id": "ag_kx91fa2b",
  "warnings": [
    {
      "code": "first_message_no_ai_disclosure",
      "message": {
        "cs": "Podle evropského AI Act (čl. 50) musí první věta prozradit, že mluví digitální asistentka. Stačí: „Dobrý den, tady digitální asistentka firmy Novák.“ Bez toho za sdělení odpovídáš ty.",
        "en": "Under the EU AI Act (Article 50), the first line must reveal that a digital assistant is speaking. For example: \"Hello, this is the digital assistant for Novak Inc.\" Without it, you are responsible for the disclosure."
      }
    }
  ]
}

New agent fields

Besides the name, prompt, voice, and number, POST /v1/agents and PATCH /v1/agents/{id} also take these fields. All are optional on creation. toolIds, transferTo, transferCondition, dataFields, and recordCalls are missing from the response for an older agent until someone sets them. goal and knowledge are always returned instead - unset as null, not as a missing key - and notifyEmail is always a boolean (missing means on). The response also always carries provider (engine or elevenlabs) - it says which platform the agent actually runs on, both values occur in production. It likewise always carries suspended (boolean) - true when the volai operator has manually suspended the agent; such an agent can't receive or make calls (agent_suspended), and the field can't be set through the API or MCP. useForOutboundTasks is the exception - only POST /v1/agents takes it, it's not in PATCH (volai, not the customer, moves an existing agent between providers; on its own it does so after turning on transferTo or calendar, or after a language change to a language in which new agents start on the engine - see the agent detail above). voicemail is only available for an agent with provider: "engine" - for others, POST/PATCH with this field fails. silencePromptSecs (a silence reminder), by contrast, is accepted and returned for either provider - for an agent on ElevenLabs the value is only saved, it's heard once the agent switches to volai's own voice engine. workflow (call phases) is available on both providers, but not equally fully - see the Call phases (workflow) section below. laughter (agent laughter) is always present too, just like goal/knowledge/notifyEmail above - for an older agent with no value set it's auto, never a missing key; accepted and stored for EITHER provider, but only heard for an agent on the engine with a Czech Cartesia voice.

Call phases (workflow)

The optional workflow field splits the call into phases (nodes). A node is a SCOPE, not a script: it only adds a prompt, knowledge and tools addition that apply while the call is in it, plus an optional line the agent speaks right on entry. The model itself decides when to move between nodes by calling a tool - you never script this as a fixed sequence. The agent's base systemPrompt should only hold what is true in EVERY phase (identity, tone, how a message is taken down); one phase's instructions belong in its own node, otherwise the node has no effect. The base prompt should also hold the two sentences without which the agent most often answers what it does not know: "Do not state or guess operational details you do not have in your instructions (opening hours, deadlines, prices, who is available) - say a colleague will confirm that." and "Only ever ask about one thing at a time."

entry is the id of the node the call starts in. edges are transitions: condition (5 to 200 characters) describes WHEN to move, and must be written about what the CALLER said (never about what the agent or a tool did) - it goes verbatim into the description of the tool the model calls to move. Limits: 2 to 8 nodes, 1 to 24 edges, at most 5 edges leaving one node, only one edge between any two nodes (in either direction, duplicate_pair); a node's prompt is up to 2,000 characters, knowledge up to 4,000, prompt plus knowledge together capped at 4,000 per node, and toolIds at most 10 tools per node.

enterPhrase is a line spoken once on entering a node (up to 160 characters). enterBehavior: "wait" tells the model not to say anything else in that same turn after it and wait for the caller instead - typically for a sensitive phase like a death announcement; it requires enterPhrase, otherwise wait_without_phrase. A node without its own enterPhrase gets a short default line on entry (in English, “I see.”) only on volai's own engine (provider: "engine"); on an agent hosted on ElevenLabs nothing plays on entry - a phase-specific line sounds more natural and is the only one that plays on both, which is why the editor keeps recommending one via the missing_enter_phrase warning.

There is no end node - phases never end a call by themselves. A call still ends only through the built-in end behavior, exactly as before.

enterBehavior: "wait" transfers to agents on ElevenLabs too, not just to volai's own voice engine (provider: "engine"); the entry line is spoken verbatim on the engine, while on ElevenLabs it goes into the phase's prompt as an instruction to say it - the model usually says something close to it, but not necessarily the exact words. A node WITHOUT its own enterPhrase says nothing at all on entry on ElevenLabs: the short default line (in English, “I see.”) is added by volai's own engine only. Two differences are bigger. A tool assigned ONLY to a node (node.toolIds) does not transfer to an agent on ElevenLabs yet - the phase runs without it there, and the response flags it with the workflow_node_tool_not_synced code; if you want it there, add it to the agent's tools as well (the toolIds field, the Advanced tab in the portal). On volai's own engine a node tool transfers unchanged. And workflowPath on the call is only written by the engine's post-call, so a call on an agent hosted on ElevenLabs never carries it, even when the call went through phases.

An invalid graph (an unreachable node, a missing entry node, a reserved tool name...) returns invalid_workflow and nothing is saved; the specific reason is always in message.

Example - a funeral home receptionist

{
  "workflow": {
    "version": 1,
    "entry": "triage",
    "nodes": [
      {
        "id": "triage",
        "label": "Triage",
        "prompt": "Find out in one question why the caller is calling. You help callers report a death, arrange a grave dig or urn interment, and request headstone work."
      },
      {
        "id": "bereavement",
        "label": "Bereavement",
        "prompt": "Find out the deceased's name, where the death occurred, whether the body is at a hospital or at home, a contact and a good time to call back. Promise a funeral home staff member will call within 15 minutes. Do not handle questions about a headstone or its price here - just say a colleague will go over that with the family, explain nothing, and return to the bereavement. Never bring up a headstone yourself.",
        "enterPhrase": "My condolences.",
        "enterBehavior": "wait"
      },
      {
        "id": "burial",
        "label": "Burial and interment",
        "prompt": "The caller needs a grave dug, an urn interred, or a tomb opened. Find out the date, cemetery and grave number, a contact, and whether a clergy member needs to be arranged."
      },
      {
        "id": "inquiry",
        "label": "Work inquiry",
        "prompt": "The caller wants new headstone work - an inscription, a repair or a grave restoration. Find out the cemetery, grave number, scope of work and a callback contact for a price."
      }
    ],
    "edges": [
      {
        "id": "triage_bereavement",
        "from": "triage",
        "to": "bereavement",
        "condition": "The caller is reporting the death of a loved one or needs funeral services."
      },
      {
        "id": "triage_burial",
        "from": "triage",
        "to": "burial",
        "condition": "The caller needs a grave dug, an urn interred, or a tomb opened."
      },
      {
        "id": "triage_inquiry",
        "from": "triage",
        "to": "inquiry",
        "condition": "The caller wants new work: a headstone, an inscription, a repair or a grave restoration."
      },
      {
        "id": "burial_bereavement",
        "from": "burial",
        "to": "bereavement",
        "condition": "The caller reports the death of a loved one during the call."
      },
      {
        "id": "inquiry_bereavement",
        "from": "inquiry",
        "to": "bereavement",
        "condition": "The caller reports the death of a loved one during the call."
      }
    ]
  }
}

A call that went through phases on volai's own voice engine (provider: "engine") also carries workflowPath in GET /v1/calls/{id} (and in the GET /v1/calls list): an array of steps {node, label, viaEdge, turnIndex, at, enterPhraseSpoken}, at as unix ms. The entry step has viaEdge: null. A call on an agent hosted on ElevenLabs never carries the field, even when it went through phases - only the engine's post-call writes it. A call with no phases omits the field entirely.

Agent drafts

A draft is a separate, work-in-progress snapshot of an agent - you save an edit into it, review it, optionally try it out (simulation below), and only then deploy it to the live agent with a single call. PUT /v1/agents/{id}/draft NEVER touches the voice provider (ElevenLabs or volai's own engine) or phone routing - it only saves the draft. POST /v1/agents/{id}/draft/publish does - it is the only draft step that actually changes the live agent.

By contrast, PATCH /v1/agents/{id} (see the Agents section above) touches the provider ITSELF, IMMEDIATELY, with no draft and no intermediate step.

Publishing can return any error of PATCH /v1/agents/{id} - it is the same write to the provider.

The agent editor in the portal (/agent/{id}) works EXCLUSIVELY through drafts - even a one-field edit calls save_agent_draft + publish_agent_draft internally.

Draft snapshot fields

draft and published share the SAME shape in every response - AgentDraftSnapshot, a complete configuration snapshot. The PUT/publish body is .strict() - unlike PATCH /v1/agents, which silently drops an unknown key, here an unknown key returns 400 validation. The workflow field is only checked for its JSON shape when a draft is saved - the graph rules (reachable phases, known tools, per-phase limits) are checked at publish and at PATCH /v1/agents/{id}, so a draft saves even with a graph that publishing rejects with invalid_workflow. Two exceptions to "complete snapshot every time": an absent silencePromptSecs in the snapshot means unchanged, not disabled and not the default 10 - on an ElevenLabs agent it carries the stored value, heard only once the agent switches to the volai engine. The same goes for an absent numberE164 - it also means unchanged, so publishing leaves the live agent's number as it is; only null disconnects it and a string attaches that number, the same three-way meaning PATCH /v1/agents/{id} already has. A string that matches the agent's current LIVE number at that moment (not the stored published snapshot) also counts as unchanged - it behaves the same as an absent key. That check is re-evaluated on every draft read against whatever number is live then, so it is not a lasting decision: if the number later moves to a different agent outside this draft, the same stored value becomes an explicit choice again and the next publish or rollback reattaches it here - not silently, but flagged with a number_changed_by_publish warning in warnings.

The remaining fields (firstMessage, voiceId, transferTo, transferCondition, recordCalls, goal, knowledge, notifyEmail) have the same meaning and limits as POST/PATCH /v1/agents - see the New agent fields table above.

operation: what's currently blocking the agent

operation (on both GET .../draft and GET .../draft/operation) is null when nothing is blocking the agent, otherwise an object { id, kind, status, expectedRevision, createdAt, updatedAt }. The kind and status values are narrowed down to what you need to decide what to do - internal details (exactly who triggered the operation, the provider's exact error text) never leave the server.

tested (on both GET .../draft and the POST .../simulate response) is { revision, testedAt } | null - when THIS EXACT draft revision was last checked with a simulation. Any further draft edit (PUT) clears the marker; a simulation is NOT a requirement for publishing, it's just an optional check of the wording before deploying.

history is a list of { revision, publishedAt } for the last publications (without the stored configuration snapshots) - only the portal keeps the full history including content.

curl https://volai.cz/v1/agents/ag_kx91fa2b/draft \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "draft": {
    "name": "Front desk",
    "language": "en",
    "systemPrompt": "You are the front desk at cafe Nula. You take pickup orders...",
    "firstMessage": "Hi, cafe Nula, what can I get you?",
    "voiceId": "milena",
    "numberE164": "+420601234567",
    "provider": "engine"
  },
  "published": {
    "name": "Front desk",
    "language": "en",
    "systemPrompt": "You are the front desk at cafe Nula. You take pickup orders...",
    "firstMessage": "Hi, this is cafe Nula, how can I help you?",
    "voiceId": "milena",
    "numberE164": "+420601234567",
    "provider": "engine"
  },
  "revision": 4,
  "tested": {
    "revision": 4,
    "testedAt": 1756118920000
  },
  "history": [
    {
      "revision": 3,
      "publishedAt": 1756118840000
    },
    {
      "revision": 2,
      "publishedAt": 1756112640000
    }
  ],
  "operation": null
}

curl -X PUT "https://volai.cz/v1/agents/ag_kx91fa2b/draft" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":3,"draft":{"name":"Front desk","language":"en","systemPrompt":"You are the front desk at cafe Nula. You take pickup orders...","firstMessage":"Hi, cafe Nula, what can I get you?","voiceId":"milena","numberE164":"+420601234567","provider":"engine"}}'

{
  "draft": {
    "name": "Front desk",
    "language": "en",
    "systemPrompt": "You are the front desk at cafe Nula. You take pickup orders...",
    "firstMessage": "Hi, cafe Nula, what can I get you?",
    "voiceId": "milena",
    "numberE164": "+420601234567",
    "provider": "engine"
  },
  "revision": 4
}

curl -X POST "https://volai.cz/v1/agents/ag_kx91fa2b/draft/publish" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: REPLACE_WITH_UNIQUE_POST_V1_AGENTS_AG_KX91FA2B_DRAFT_PUBLISH_ID" \
  -d '{"expectedRevision":4}'

{
  "revision": 5,
  "published": {
    "name": "Front desk",
    "language": "en",
    "systemPrompt": "You are the front desk at cafe Nula. You take pickup orders...",
    "firstMessage": "Hi, cafe Nula, what can I get you?",
    "voiceId": "milena",
    "numberE164": "+420601234567",
    "provider": "engine"
  }
}

curl -X POST "https://volai.cz/v1/agents/ag_kx91fa2b/draft/rollback" \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":4,"targetRevision":2}'

{
  "revision": 5,
  "published": {
    "name": "Front desk",
    "language": "en",
    "systemPrompt": "You are the front desk at cafe Nula. You take pickup orders...",
    "firstMessage": "Hi, cafe Nula, what can I get you?",
    "voiceId": "milena",
    "numberE164": "+420601234567",
    "provider": "engine"
  }
}

curl https://volai.cz/v1/agents/ag_kx91fa2b/draft/operation \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "operation": {
    "id": "ado_4f2a91cd",
    "kind": "publish",
    "status": "uncertain",
    "expectedRevision": 4,
    "createdAt": 1756118900000,
    "updatedAt": 1756118905000
  }
}

curl -X POST https://volai.cz/v1/agents/ag_kx91fa2b/draft/operation \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operationId":"ado_4f2a91cd","decision":"acknowledge_live_state"}'

{
  "reconciled": true,
  "revision": 5
}

curl -X POST https://volai.cz/v1/agents/ag_kx91fa2b/simulate \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":4,"message":"Dobry den"}'

{
  "revision": 4,
  "text": "Hi, cafe Nula, what can I get you?",
  "usage": {
    "inputTokens": 412,
    "outputTokens": 58
  },
  "tested": {
    "revision": 4,
    "testedAt": 1756118920000
  }
}

Voices

The voice catalog for voiceId on POST/PATCH /v1/agents. provider says where the agent runs; useForOutboundTasks makes the initial choice. On an existing engine agent, PATCH accepts every catalog voice EXCEPT the ElevenLabs voices (katty, the older anet); katty and raw ElevenLabs IDs are valid only on ElevenLabs (anet stays there only on agents that already have it). POST has one exception: explicit true replaces a recognized voice unavailable on the engine, including katty, with the engine default. If omission selects the engine through the deployment default, the same value returns 400; a raw ElevenLabs ID is always rejected for the engine. ?provider=engine returns engine voices and ?provider=elevenlabs returns ElevenLabs voices. An unrecognized value returns 400 validation and lists the valid values. The same catalog, with a description of each voice, is on the Voice agent.

curl https://volai.cz/v1/voices \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "voices": [
    {
      "id": "milena",
      "name": "Milena",
      "gender": "female",
      "provider": "cartesia",
      "tone": "calm, warm",
      "description": "The default volai voice - calm and natural, a good fit for most agents.",
      "languages": [
        "cs"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/milena-studio.mp3",
        "phone": "https://volai.cz/hlasy/milena-telefon.mp3"
      },
      "default": true
    },
    {
      "id": "jan",
      "name": "Jan",
      "gender": "male",
      "provider": "cartesia",
      "tone": "calm, matter-of-fact",
      "description": "The male counterpart to Milena - matter-of-fact, easy-to-follow delivery.",
      "languages": [
        "cs"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/jan-studio.mp3",
        "phone": "https://volai.cz/hlasy/jan-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "tereza",
      "name": "Tereza",
      "gender": "female",
      "provider": "cartesia",
      "tone": "professional, structured",
      "description": "The second female voice - professional, well-structured delivery.",
      "languages": [
        "cs"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/tereza-studio.mp3",
        "phone": "https://volai.cz/hlasy/tereza-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "marek",
      "name": "Marek",
      "gender": "male",
      "provider": "cartesia",
      "tone": "calm, resonant",
      "description": "The second male voice - calm, resonant delivery for longer calls.",
      "languages": [
        "cs"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/marek-studio.mp3",
        "phone": "https://volai.cz/hlasy/marek-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "katarina",
      "name": "Katarina",
      "gender": "female",
      "provider": "cartesia",
      "tone": "calm, natural",
      "description": "Slovak female voice - calm, natural delivery.",
      "languages": [
        "sk"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/katarina-studio.mp3",
        "phone": "https://volai.cz/hlasy/katarina-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "peter",
      "name": "Peter",
      "gender": "male",
      "provider": "cartesia",
      "tone": "matter-of-fact, clear",
      "description": "Slovak male voice - matter-of-fact, easy-to-follow delivery.",
      "languages": [
        "sk"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/peter-studio.mp3",
        "phone": "https://volai.cz/hlasy/peter-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "skylar",
      "name": "Skylar",
      "gender": "female",
      "provider": "cartesia",
      "tone": "calm, friendly",
      "description": "English female voice - calm, friendly delivery.",
      "languages": [
        "en"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/skylar-studio.mp3",
        "phone": "https://volai.cz/hlasy/skylar-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "daniel",
      "name": "Daniel",
      "gender": "male",
      "provider": "cartesia",
      "tone": "matter-of-fact, confident",
      "description": "English male voice - matter-of-fact, confident delivery.",
      "languages": [
        "en"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/daniel-studio.mp3",
        "phone": "https://volai.cz/hlasy/daniel-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "alina",
      "name": "Alina",
      "gender": "female",
      "provider": "cartesia",
      "tone": "calm, warm",
      "description": "German female voice - calm, warm delivery.",
      "languages": [
        "de"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/alina-studio.mp3",
        "phone": "https://volai.cz/hlasy/alina-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "lukas",
      "name": "Lukas",
      "gender": "male",
      "provider": "cartesia",
      "tone": "matter-of-fact, clear",
      "description": "German male voice - matter-of-fact, easy-to-follow delivery.",
      "languages": [
        "de"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/lukas-studio.mp3",
        "phone": "https://volai.cz/hlasy/lukas-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "ewa",
      "name": "Ewa",
      "gender": "female",
      "provider": "cartesia",
      "tone": "calm, natural",
      "description": "Polish female voice - calm, natural delivery.",
      "languages": [
        "pl"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/ewa-studio.mp3",
        "phone": "https://volai.cz/hlasy/ewa-telefon.mp3"
      },
      "default": false
    },
    {
      "id": "kacper",
      "name": "Kacper",
      "gender": "male",
      "provider": "cartesia",
      "tone": "matter-of-fact, confident",
      "description": "Polish male voice - matter-of-fact, confident delivery.",
      "languages": [
        "pl"
      ],
      "preview": {
        "studio": "https://volai.cz/hlasy/kacper-studio.mp3",
        "phone": "https://volai.cz/hlasy/kacper-telefon.mp3"
      },
      "default": false
    }
  ]
}

The tone field describes the voice's nature (calm, businesslike); languages holds the language codes the voice speaks in - cs: Milena, Jan, Tereza, Marek; sk: Katarina, Peter; en: Skylar, Daniel; de: Alina, Lukas; pl: Ewa, Kacper; preview provides the URLs of the studio and telephone preview samples; default marks the catalog's recommended entry - in the portal it only carries a 'Default' badge on the card and does not preselect anything by itself. A new agent created without voiceId does not switch to it - it inherits its provider's default voice (Milena on the engine, the template's voice on ElevenLabs; see the Agents section above).

Agent tools

A tool is the address of your API that the agent calls in the middle of a call (verify an order, log a booking) and uses the response in speech. A tool belongs to the account and is assigned to an agent via toolIds - creating a tool by itself doesn't change any agent.

Limits: at most 10 tools per account, 10 parameters and 5 headers per tool, timeoutSecs 5 to 30 (20 by default). The address must be https and public - we reject internal networks and loopback (private_address), since otherwise our server could be used to probe someone else's infrastructure.

curl https://volai.cz/v1/tools \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "tools": [
    {
      "id": "tl_5c2a91f4",
      "name": "verify_order",
      "label": "Verify order",
      "description": "Looks up order status by number. Use when the caller asks where their order is.",
      "url": "https://api.yourapp.com/orders",
      "method": "POST",
      "headers": { "Authorization": "Bear***" },
      "params": [
        {
          "name": "order_number",
          "type": "string",
          "source": "llm",
          "description": "The order number the caller dictated.",
          "required": true
        },
        { "name": "phone", "type": "string", "source": "caller_number" },
        { "name": "source", "type": "string", "source": "constant", "constantValue": "phone" }
      ],
      "timeoutSecs": 20,
      "createdAt": 1756111000000,
      "updatedAt": 1756111000000
    }
  ]
}

curl -X POST https://volai.cz/v1/tools \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Verify order",
    "description": "Looks up order status by number. Use when the caller asks where their order is.",
    "url": "https://api.yourapp.com/orders",
    "method": "POST",
    "headers": { "Authorization": "Bearer your_key" },
    "params": [
      {
        "name": "order_number",
        "type": "string",
        "source": "llm",
        "description": "The order number the caller dictated.",
        "required": true
      },
      { "name": "phone", "type": "string", "source": "caller_number" },
      { "name": "source", "type": "string", "source": "constant", "constantValue": "phone" }
    ],
    "timeoutSecs": 20
  }'

{
  "tool": {
    "id": "tl_5c2a91f4",
    "name": "verify_order",
    "label": "Verify order",
    "description": "Looks up order status by number. Use when the caller asks where their order is.",
    "url": "https://api.yourapp.com/orders",
    "method": "POST",
    "headers": { "Authorization": "Bear***" },
    "params": [
      {
        "name": "order_number",
        "type": "string",
        "source": "llm",
        "description": "The order number the caller dictated.",
        "required": true
      },
      { "name": "phone", "type": "string", "source": "caller_number" },
      { "name": "source", "type": "string", "source": "constant", "constantValue": "phone" }
    ],
    "timeoutSecs": 20,
    "createdAt": 1756111000000,
    "updatedAt": 1756111000000
  }
}

curl https://volai.cz/v1/tools/tl_5c2a91f4 \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "tool": {
    "id": "tl_5c2a91f4",
    "name": "verify_order",
    "label": "Verify order",
    "description": "Looks up order status by number. Use when the caller asks where their order is.",
    "url": "https://api.yourapp.com/orders",
    "method": "POST",
    "headers": { "Authorization": "Bear***" },
    "params": [
      {
        "name": "order_number",
        "type": "string",
        "source": "llm",
        "description": "The order number the caller dictated.",
        "required": true
      },
      { "name": "phone", "type": "string", "source": "caller_number" },
      { "name": "source", "type": "string", "source": "constant", "constantValue": "phone" }
    ],
    "timeoutSecs": 20,
    "createdAt": 1756111000000,
    "updatedAt": 1756111000000,
    "agents": [{ "id": "ag_kx91fa2b", "name": "Front desk" }]
  }
}

curl -X PATCH https://volai.cz/v1/tools/tl_5c2a91f4 \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeoutSecs": 10}'

{
  "tool": {
    "id": "tl_5c2a91f4",
    "name": "verify_order",
    "label": "Verify order",
    "description": "Looks up order status by number. Use when the caller asks where their order is.",
    "url": "https://api.yourapp.com/orders",
    "method": "POST",
    "headers": { "Authorization": "Bear***" },
    "params": [
      {
        "name": "order_number",
        "type": "string",
        "source": "llm",
        "description": "The order number the caller dictated.",
        "required": true
      },
      { "name": "phone", "type": "string", "source": "caller_number" },
      { "name": "source", "type": "string", "source": "constant", "constantValue": "phone" }
    ],
    "timeoutSecs": 10,
    "createdAt": 1756111000000,
    "updatedAt": 1756111890000
  }
}

curl -X DELETE https://volai.cz/v1/tools/tl_5c2a91f4 \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "deleted": true,
  "agents": [
    { "id": "ag_kx91fa2b", "name": "Front desk" }
  ]
}

curl -X POST https://volai.cz/v1/tools/test \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.yourapp.com/orders", "method": "GET", "params": [{"name": "order", "type": "string", "source": "llm", "description": "Order number."}]}'

{
  "status": 200,
  "durationMs": 214,
  "body": "{\"status\":\"shipped\"}",
  "note": null
}

curl -X POST https://volai.cz/v1/tools/tl_5c2a91f4/test \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "status": 200,
  "durationMs": 214,
  "body": "{\"status\":\"shipped\"}",
  "note": null
}

A tool's parameters: the source field

Every parameter has a name, a type (string, number, boolean), and a source - where its value comes from. For GET, parameters go into the query string; for POST, into the JSON body.

Test call

"Have your agent call you" - a real outbound call through makeAgentCall, just with its own daily cap of 3 calls per account (across every agent), so a test call can't be used as a back door around the normal calling limit.

curl -X POST https://volai.cz/v1/agents/ag_kx91fa2b/test-call \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456"}'

{
  "id": "c_9d4e2b7f",
  "status": "initiated"
}

Relay - bring your own agent

A one-off rental of a SIP name from the relay pool, for an outbound call from your own voice agent (ElevenLabs or any other platform) - with no agent surcharge (that's normally 2.50 CZK/min (~EUR 0.10), but here you pay for it on your own platform). The full setup guide for ElevenLabs is on the Bring your own agent.

curl -X POST https://volai.cz/v1/relay \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "from": "+420601234567"}'

{
  "id": "rl_4f2a91cd",
  "sipName": "volai_relay_2",
  "sipUri": "sip:volai_relay_2@sip.volai.cz",
  "expiresAt": 1756111760000,
  "callId": "c_9d4e2b7f"
}

curl https://volai.cz/v1/relay \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "leases": [
    {
      "id": "rl_4f2a91cd",
      "sipName": "volai_relay_2",
      "sipUri": "sip:volai_relay_2@sip.volai.cz",
      "from": "+420601234567",
      "to": "+420777123456",
      "callId": "c_9d4e2b7f",
      "status": "active",
      "createdAt": 1756111640000,
      "expiresAt": 1756111760000
    }
  ]
}

curl -X DELETE https://volai.cz/v1/relay/rl_4f2a91cd \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "cancelled": true
}

Do-not-call list (DNC)

Numbers your agent (your own or the built-in one) must not call - whether through POST /v1/calls, a test call, or relay. DNC only applies to calls - sending an SMS to a listed number is not restricted.

Besides the manual list, volai automatically (and temporarily) blocks a destination on its own - after 3 failed attempts within 24 hours (busy, unanswered, rejected) it stops calling that number for 30 days. The block can be lifted in the portal (Settings) or via POST /v1/dnc/{e164}/unblock - otherwise it expires on its own.

curl https://volai.cz/v1/dnc \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "numbers": ["+420777998877"],
  "blocked": [
    {
      "e164": "+420777123456",
      "blockedAt": 1757600000000,
      "expiresAt": 1760192000000
    }
  ]
}

curl -X POST https://volai.cz/v1/dnc \
  -H "Authorization: Bearer vk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"e164": "+420777998877"}'

{
  "added": true,
  "e164": "+420777998877"
}

curl -X DELETE "https://volai.cz/v1/dnc/+420777998877" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "removed": true,
  "e164": "+420777998877"
}

curl -X POST "https://volai.cz/v1/dnc/+420777998877/unblock" \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "unblocked": true,
  "e164": "+420777998877"
}

Webhook

curl https://volai.cz/v1/webhook \
  -H "Authorization: Bearer vk_YOUR_KEY"

{
  "url": "https://tvoje-appka.cz/webhooks/volai",
  "events": ["call.completed", "call.failed", "message.sent"],
  "recentDeliveries": [
    {
      "id": "whd_9f2b7a1c4e",
      "event": "call.completed",
      "url": "https://tvoje-appka.cz/webhooks/volai",
      "status": 200,
      "attempts": 1,
      "ok": true,
      "durationMs": 184,
      "createdAt": 1756111641000
    }
  ]
}