{"openapi":"3.1.0","info":{"title":"NestVoice API","description":"\nPlace AI phone calls and manage your agents from your own software.\n\n## Quick start\n\n1. Open **Developers** in the NestVoice dashboard and create an API key. Choose only the scopes you need.\n2. Send it as `Authorization: Bearer nv_live_...` from your **server** (never from a browser or mobile app).\n3. `POST /v1/calls` with an `agent_id` and a `to` number.\n\n```bash\ncurl https://api.nestvoiceai.com/v1/calls \\\n  -H \"Authorization: Bearer $NESTVOICE_API_KEY\" \\\n  -H \"Idempotency-Key: order-1042-reminder\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"agent_id\": \"AGENT_ID\", \"to\": \"+919876543210\",\n       \"variables\": {\"customer_name\": \"Asha\"}, \"metadata\": {\"order_id\": \"A-1042\"}}'\n```\n\nThe API is included with every paid plan. Calls are billed exactly like dashboard calls (the per-minute\nprice of the agent's voice tier, from your credits) and go out from your own connected numbers.\n\n## Agents\n\nAn *agent* is what you configure in the dashboard: prompt, greeting, voice, language, knowledge base and\nfollow-ups. Put `{{placeholders}}` in the greeting or prompt (for example `{{customer_name}}`) and send their\nvalues as `variables` when you place a call; `business_name` and `agent_name` are filled in for you.\n\n## Errors\n\nEvery error has the same shape:\n\n```json\n{\"error\": {\"type\": \"invalid_request\", \"code\": \"invalid_phone_number\",\n           \"message\": \"...\", \"request_id\": \"req_...\"}}\n```\n\n`type` is one of `invalid_request`, `authentication`, `permission`, `not_found`, `conflict`,\n`insufficient_credits`, `rate_limited`, `server_error`. Branch on `code`; the message is for people.\nEvery response carries an `X-Request-Id` header.\n\n## Rate limits\n\n120 requests per minute per key, and 30 `POST /v1/calls` per minute per key. Every response has\n`X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (unix seconds); a `429` also has\n`Retry-After`.\n\n## Pagination\n\nList endpoints take `limit` (1-100, default 20) and `cursor`, newest first, and return\n`{\"object\": \"list\", \"data\": [...], \"has_more\": true, \"next_cursor\": \"...\"}`. Pass `next_cursor` back as `cursor`.\n\n## Idempotency\n\n`POST /v1/calls` and `POST /v1/agents` accept an `Idempotency-Key` header (8-255 characters). The same key and\nbody within 24 hours returns the first response again (`Idempotent-Replayed: true`) and places no second call.\nThe same key with a different body is `409 idempotency_key_reused`; a request still running is\n`409 idempotency_key_in_use`.\n\n## Webhooks\n\nAdd an endpoint on the Developers page and choose the events: `call.completed` (an answered call ended),\n`call.failed` (not answered, busy or failed), `lead.qualified`, `meeting.created`. The body is JSON with `id`,\n`event`, `created_at`, `status`, `agent_id`, `to`, `from`, `metadata`, `variables`, `recording_available`,\n`cost_inr`, `failure_reason`, `summary`, `outcome` and the `transcript`.\n\nHeaders: `X-NestVoice-Event`, `X-NestVoice-Delivery` (unique per delivery), `X-NestVoice-Timestamp` and\n`X-NestVoice-Signature-256: t=<timestamp>,v1=<hex>` where `v1` is the HMAC-SHA256, keyed with your webhook\nsecret, of `\"<timestamp>.<raw body>\"`. Reject a timestamp older than 5 minutes. A failed delivery (network\nerror, 429 or 5xx) is retried up to 3 times with exponential backoff; the history is on the Developers page.\n","contact":{"name":"NestVoice support","url":"https://nestvoiceai.com/developers"},"version":"1.0.0"},"paths":{"/me":{"get":{"tags":["Workspace"],"summary":"Who am I?","description":"The workspace this key belongs to, the key itself, the credit balance, the plan and the number of lines. Works with any scope: a handy first call to check a key.","operationId":"me_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/agents":{"get":{"tags":["Agents"],"summary":"List agents","description":"Your agents (the same ones as on the Campaigns page), newest first. Requires scope `agents:read`.","operationId":"list_agents_agents_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["outbound","inbound","bidirectional"],"type":"string"},{"type":"null"}],"description":"Only agents of this type.","title":"Type"},"description":"Only agents of this type."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentList"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Agents"],"summary":"Create an agent","description":"Creates an agent with the same checks as the dashboard (plan, voice tier, prompt rules, content safety). Requires scope `agents:write`. Send an `Idempotency-Key` header to make retries safe.","operationId":"create_agent_agents_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"8-255 characters.","title":"Idempotency-Key"},"description":"8-255 characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/agents/{agent_id}":{"get":{"tags":["Agents"],"summary":"Get an agent","description":"Requires scope `agents:read`.","operationId":"get_agent_agents__agent_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Agents"],"summary":"Update an agent","description":"Change any of the fields. Same checks as editing it in the dashboard. Requires scope `agents:write`.","operationId":"patch_agent_agents__agent_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/voices":{"get":{"tags":["Voices"],"summary":"List voices","description":"The voices your workspace can use: only voice tiers that are switched on, included in your plan and configured. Use a voice `id` and its `tier` when you create an agent. Requires scope `agents:read`.","operationId":"list_voices_voices_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"tier","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only this voice tier.","title":"Tier"},"description":"Only this voice tier."},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"e.g. `hi-IN`.","title":"Language"},"description":"e.g. `hi-IN`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceList"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/phone-numbers":{"get":{"tags":["Phone numbers"],"summary":"List your phone numbers","description":"The numbers connected to your workspace: what `from` may be when you place a call. Requires scope `calls:read`.","operationId":"list_numbers_phone_numbers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneNumberList"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/calls":{"post":{"tags":["Calls"],"summary":"Place a call","description":"Places one outbound call with one of your agents. It behaves exactly like a call from the dashboard: same agent, voice, knowledge base, billing (per-minute price of the agent's voice tier), line limits and your own connected numbers.\n\nChecks, in order: credits and plan (402), your do-not-call list (403 `do_not_call`), compliance (403), the agent's calling hours (409 `outside_calling_hours`), then lines and numbers (409, with the reason as `code`).\n\nThe call is answered asynchronously: this returns as soon as it is ringing. Follow it with the `call.completed` / `call.failed` webhook or `GET /v1/calls/{id}`.\n\nRequires scope `calls:write`. Limit: 30 per minute per key. Send an `Idempotency-Key` header to make retries safe: the same key and body returns the same call (`Idempotent-Replayed: true`).","operationId":"create_call_calls_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"8-255 characters.","title":"Idempotency-Key"},"description":"8-255 characters."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Call"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid phone number or number not yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Not enough credits, or plan expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Outside calling hours, lines busy, agent cannot dial, or idempotency conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Calls"],"summary":"List calls","description":"Every call of your workspace (API, dashboard, campaigns and inbound), newest first. Requires scope `calls:read`.","operationId":"list_calls_calls_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"direction","in":"query","required":false,"schema":{"anyOf":[{"enum":["outbound","inbound"],"type":"string"},{"type":"null"}],"title":"Direction"}},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601.","title":"Created After"},"description":"ISO 8601."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO 8601.","title":"Created Before"},"description":"ISO 8601."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallList"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/calls/{call_id}":{"get":{"tags":["Calls"],"summary":"Get a call","description":"Requires scope `calls:read`.","operationId":"get_call_calls__call_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","title":"Call Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Call"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such call in your workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/calls/{call_id}/transcript":{"get":{"tags":["Calls"],"summary":"Get a call's transcript","description":"The conversation turn by turn. `role` is `agent` (the AI), `caller` or `human` (a person who took over). Empty until the call has ended. Requires scope `calls:read`.","operationId":"get_transcript_calls__call_id__transcript_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","title":"Call Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcript"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such call in your workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/calls/{call_id}/recording":{"get":{"tags":["Calls"],"summary":"Download a call's recording","description":"The call's audio as `audio/mpeg`. 404 `recording_not_available` when the agent does not record calls or the recording is not ready. Requires scope `calls:read`.","operationId":"get_recording_calls__call_id__recording_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","title":"Call Id"}}],"responses":{"200":{"description":"The recording (MP3).","content":{"audio/mpeg":{}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such call in your workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/calls/{call_id}/end":{"post":{"tags":["Calls"],"summary":"End a call","description":"Hangs up a call that is still queued, ringing or in progress. Requires scope `calls:write`.","operationId":"end_call_calls__call_id__end_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","title":"Call Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Call"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing scope, or no paid plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such call in your workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The call already ended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Agent":{"properties":{"id":{"type":"string","title":"Id"},"object":{"type":"string","const":"agent","title":"Object","default":"agent"},"name":{"type":"string","title":"Name"},"type":{"type":"string","enum":["outbound","inbound","bidirectional"],"title":"Type"},"status":{"type":"string","title":"Status"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"voice_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voice Tier"},"voice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voice"},"greeting":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Greeting","description":"The opening line."},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt","description":"The instructions the AI follows."},"goal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Goal","description":"What the calls are about."},"variables":{"items":{"type":"string"},"type":"array","title":"Variables","description":"`{{placeholders}}` found in the greeting and prompt (except the built-in `business_name` and `agent_name`). Send values for them in `variables` when you place a call."},"knowledge_base_ids":{"items":{"type":"string"},"type":"array","title":"Knowledge Base Ids"},"collected_fields":{"items":{"type":"object"},"type":"array","title":"Collected Fields"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","name","type","status"],"title":"Agent"},"AgentCreate":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"type":{"type":"string","enum":["outbound","inbound","bidirectional"],"title":"Type","default":"outbound"},"prompt":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}],"title":"Prompt"},"greeting":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Greeting"},"goal":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Goal"},"language":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Language","description":"e.g. `en-IN`, `hi-IN`, `te-IN`."},"voice_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voice Tier","description":"See `GET /v1/voices`."},"voice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voice","description":"A voice `id` from `GET /v1/voices`."},"knowledge_base_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Knowledge Base Ids"},"collected_fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/CollectedField"},"type":"array","maxItems":30},{"type":"null"}],"title":"Collected Fields"}},"additionalProperties":false,"type":"object","required":["name"],"title":"AgentCreate","example":{"collected_fields":[{"key":"confirmed","label":"Confirmed","type":"boolean"}],"goal":"Confirm tomorrow's appointment.","greeting":"Hello {{customer_name}}, this is {{business_name}} calling about your appointment.","language":"en-IN","name":"Appointment reminder","prompt":"You remind customers of their appointment on {{appointment_time}} and offer to reschedule if they cannot make it. Keep replies short.","type":"outbound","voice_tier":"sarvam"}},"AgentList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Agent"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"AgentList"},"AgentPatch":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Name"},"type":{"anyOf":[{"type":"string","enum":["outbound","inbound","bidirectional"]},{"type":"null"}],"title":"Type"},"prompt":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}],"title":"Prompt"},"greeting":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Greeting"},"goal":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Goal"},"language":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Language"},"voice_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voice Tier"},"voice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voice"},"knowledge_base_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Knowledge Base Ids"},"collected_fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/CollectedField"},"type":"array","maxItems":30},{"type":"null"}],"title":"Collected Fields"}},"additionalProperties":false,"type":"object","title":"AgentPatch"},"Call":{"properties":{"id":{"type":"string","title":"Id"},"object":{"type":"string","const":"call","title":"Object","default":"call"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"},"direction":{"type":"string","enum":["outbound","inbound"],"title":"Direction"},"status":{"type":"string","title":"Status","description":"`queued`, `ringing`, `in-progress`, `completed`, `failed`, `no-answer`, `busy` or `canceled`."},"to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To"},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From"},"variables":{"type":"object","title":"Variables"},"metadata":{"type":"object","title":"Metadata"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"},"answered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Answered At"},"ended_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ended At"},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Seconds"},"billed_minutes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Billed Minutes"},"cost_inr":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Inr"},"cost_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost Credits"},"voice_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voice Tier"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"outcome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Outcome"},"sentiment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"},"collected_data":{"type":"object","title":"Collected Data"},"recording_available":{"type":"boolean","title":"Recording Available","default":false},"failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Failure Reason"},"source":{"type":"string","enum":["api","dashboard","campaign","inbound"],"title":"Source"}},"type":"object","required":["id","direction","status","source"],"title":"Call"},"CallCreate":{"properties":{"agent_id":{"type":"string","title":"Agent Id","description":"An outbound or bidirectional agent of your workspace."},"to":{"type":"string","title":"To","description":"Indian number: `+919876543210`, `919876543210`, `09876543210` or `9876543210`."},"from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From","description":"One of your own numbers (`GET /v1/phone-numbers`). Default: the number the dashboard would pick."},"variables":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Variables","description":"Values for the agent's `{{placeholders}}`, for this call only. Up to 50 keys (`^[A-Za-z_][A-Za-z0-9_]{0,40}$`), string values up to 500 characters."},"metadata":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Metadata","description":"Your own data (string, number or boolean values; up to 50 keys, 8 KB). Returned on the call and in webhooks; never shown to the AI."}},"additionalProperties":false,"type":"object","required":["agent_id","to"],"title":"CallCreate","example":{"agent_id":"3f0f6a54-2f0c-4a2c-b1c2-6d3d1f1e9a10","from":"+918012345678","metadata":{"order_id":"A-1042"},"to":"+919876543210","variables":{"appointment_time":"4 pm tomorrow","customer_name":"Asha"}}},"CallList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Call"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"CallList"},"CollectedField":{"properties":{"key":{"type":"string","pattern":"^[A-Za-z_][A-Za-z0-9_]{0,40}$","title":"Key","description":"Name the value is returned under in `collected_data`."},"label":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Label"},"type":{"type":"string","enum":["text","number","enum","date","boolean"],"title":"Type","default":"text"},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options","description":"Allowed values when `type` is `enum`."},"required":{"type":"boolean","title":"Required","default":false}},"type":"object","required":["key"],"title":"CollectedField"},"Credits":{"properties":{"balance_inr":{"type":"number","title":"Balance Inr"},"balance_credits":{"type":"integer","title":"Balance Credits"}},"type":"object","required":["balance_inr","balance_credits"],"title":"Credits"},"ErrorBody":{"properties":{"type":{"type":"string","title":"Type","description":"One of `invalid_request`, `authentication`, `permission`, `not_found`, `conflict`, `insufficient_credits`, `rate_limited`, `server_error`."},"code":{"type":"string","title":"Code","description":"Stable machine-readable code, e.g. `invalid_api_key`."},"message":{"type":"string","title":"Message","description":"Human-readable explanation."},"request_id":{"type":"string","title":"Request Id","description":"Quote this when you contact support."}},"type":"object","required":["type","code","message","request_id"],"title":"ErrorBody"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse","example":{"error":{"code":"invalid_api_key","message":"The API key is not valid.","request_id":"req_8f2c1a9d3b7e4f60","type":"authentication"}}},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"KeyInfo":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"prefix":{"type":"string","title":"Prefix"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"}},"type":"object","required":["id","name","prefix","scopes"],"title":"KeyInfo"},"PhoneNumber":{"properties":{"id":{"type":"string","title":"Id"},"object":{"type":"string","const":"phone_number","title":"Object","default":"phone_number"},"number":{"type":"string","title":"Number"},"provider":{"type":"string","title":"Provider"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"}},"type":"object","required":["id","number","provider"],"title":"PhoneNumber"},"PhoneNumberList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/PhoneNumber"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data"],"title":"PhoneNumberList"},"PlanInfo":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"valid_until":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Valid Until"}},"type":"object","title":"PlanInfo"},"Transcript":{"properties":{"object":{"type":"string","const":"transcript","title":"Object","default":"transcript"},"call_id":{"type":"string","title":"Call Id"},"data":{"items":{"$ref":"#/components/schemas/TranscriptTurn"},"type":"array","title":"Data"}},"type":"object","required":["call_id","data"],"title":"Transcript"},"TranscriptTurn":{"properties":{"role":{"type":"string","enum":["agent","caller","human"],"title":"Role"},"text":{"type":"string","title":"Text"},"timestamp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timestamp"}},"type":"object","required":["role","text"],"title":"TranscriptTurn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"Voice":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"tier":{"type":"string","title":"Tier"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"accent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accent"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["id","name","tier"],"title":"Voice"},"VoiceList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Voice"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data"],"title":"VoiceList"},"Workspace":{"properties":{"object":{"type":"string","const":"workspace","title":"Object","default":"workspace"},"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"key":{"$ref":"#/components/schemas/KeyInfo"},"credits":{"$ref":"#/components/schemas/Credits"},"plan":{"$ref":"#/components/schemas/PlanInfo"},"lines":{"type":"integer","title":"Lines","description":"Calls your workspace can run at the same time."}},"type":"object","required":["id","name","key","credits","plan","lines"],"title":"Workspace"}},"securitySchemes":{"HTTPBearer":{"type":"http","description":"`Authorization: Bearer nv_live_<secret>`. Create keys on the Developers page of the dashboard. Server-to-server only: never put a key in a browser or mobile app.","scheme":"bearer","bearerFormat":"nv_live_..."}}},"tags":[{"name":"Workspace","description":"Check your key and balance."},{"name":"Agents","description":"The AI agents you call with."},{"name":"Voices","description":"Voices you can give an agent."},{"name":"Phone numbers","description":"Your own numbers (`from`)."},{"name":"Calls","description":"Place calls and read their results."}],"servers":[{"url":"/v1"}]}