{ "openapi": "3.1.0", "info": { "title": "VaniAgent Developer API", "version": "1.0.0", "description": "Curated public API for VaniAgent agents, calls, contacts, campaigns, knowledge, TTS, and web widgets." }, "servers": [ { "url": "https://api.vaniagent.com" } ], "paths": { "/api/developer/v1/agents": { "get": { "tags": [ "developer" ], "summary": "List your agents", "description": "Returns all voice agents belonging to your account.\n\nUse the `id` field as `agent_id` when initiating calls (`POST /v1/calls`) or creating campaigns (`POST /v1/campaigns`).\n\n**Requires** `X-API-Key` header.", "operationId": "list_developer_agents_api_developer_v1_agents_get", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperAgentResponse" }, "title": "Response List Developer Agents Api Developer V1 Agents Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "developer" ], "summary": "Create an agent", "description": "Create a new voice agent. The agent's `id` is used as `agent_id` in `POST /v1/calls`.\n\nIf `greeting_line` is provided the greeting audio is pre-generated synchronously before the response is returned — same behaviour as the dashboard. The `greeting_audio_generated` flag in the response tells you whether it succeeded.\n\nUse `GET /v1/tts-config` to discover valid `tts_provider`, `voice`, and `tts_language` values.\n\nUse `GET /v1/phone-numbers` to discover valid `phone_number_id` values.\n\n**Requires** `X-API-Key` header.", "operationId": "create_developer_agent_api_developer_v1_agents_post", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperAgentCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperAgentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/agents/{agent_id}": { "get": { "tags": [ "developer" ], "summary": "Get an agent", "description": "Fetch a single agent by ID.\n\n**Requires** `X-API-Key` header.", "operationId": "get_developer_agent_api_developer_v1_agents__agent_id__get", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperAgentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "developer" ], "summary": "Update an agent", "description": "Update an existing agent's configuration.\n\nOnly provided fields are updated — omitted fields remain unchanged.\n\nIf `greeting_line`, `voice`, or `tts_provider` are changed, the greeting audio is automatically regenerated.\n\n**Requires** `X-API-Key` header.", "operationId": "update_developer_agent_api_developer_v1_agents__agent_id__patch", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperAgentUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperAgentResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "developer" ], "summary": "Delete an agent", "description": "Permanently delete an agent.\n\nThis action is **irreversible**. The agent's greeting audio file is also deleted.\n\n**Requires** `X-API-Key` header.", "operationId": "delete_developer_agent_api_developer_v1_agents__agent_id__delete", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/agents/{agent_id}/toggle": { "patch": { "tags": [ "developer" ], "summary": "Toggle agent active status", "description": "Toggle an agent's active/inactive status.\n\nInactive agents cannot be used for calls or campaigns.\n\n**Requires** `X-API-Key` header.", "operationId": "toggle_agent_api_developer_v1_agents__agent_id__toggle_patch", "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentToggleResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/calls": { "post": { "tags": [ "developer" ], "summary": "Initiate an outbound call", "description": "Programmatically trigger an outbound call using the agent configured in your dashboard. The 'from' number is automatically derived from the agent's configured phone number.\n\n**Requires** `X-API-Key` header with your developer API key.\n\n**Credit-gated:** Any tier can call. Rate limited per minute (see your plan for limits).", "operationId": "initiate_developer_call_api_developer_v1_calls_post", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperCallRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperCallResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "developer" ], "summary": "List call logs", "description": "Returns paginated call history for the authenticated user.\n\nSupports optional filtering by `status` and date range. Results are sorted newest-first.\n\n**Requires** `X-API-Key` header.", "operationId": "list_developer_calls_api_developer_v1_calls_get", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "title": "Page" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "title": "Limit" } }, { "name": "status_filter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Filter" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "End Date" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperCallLogsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/calls/{call_id}": { "get": { "tags": [ "developer" ], "summary": "Get call status", "description": "Check the status of a previously initiated call. If the call has completed, the full call data (transcript, recording, etc.) is returned. If the call is still in progress, only the status is returned.", "operationId": "get_call_status_api_developer_v1_calls__call_id__get", "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/calls/stats": { "get": { "tags": [ "developer" ], "summary": "Get call statistics", "description": "Returns aggregated call statistics including total calls, success rate, average duration, and total cost.\n\n**Requires** `X-API-Key` header.", "operationId": "get_call_stats_api_developer_v1_calls_stats_get", "parameters": [ { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Start Date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "End Date" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallStatsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/calls/{call_id}/cancel": { "post": { "tags": [ "developer" ], "summary": "Cancel a call", "description": "Cancel an in-progress or queued call.\n\nOnly calls with status 'queued' or 'in_progress' can be cancelled.\n\n**Requires** `X-API-Key` header.", "operationId": "cancel_call_api_developer_v1_calls__call_id__cancel_post", "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallCancelResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/calls/bulk-initiate": { "post": { "tags": [ "developer" ], "summary": "Initiate multiple calls", "description": "Initiate up to 100 outbound calls in a single request.\n\nEach call uses the same agent but can have different destination numbers, contact names, and custom instructions.\n\nPartial failures do not abort the batch — the response includes detailed results for each call.\n\n**Requires** `X-API-Key` header.", "operationId": "bulk_initiate_calls_api_developer_v1_calls_bulk_initiate_post", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCallRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCallResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/contacts": { "post": { "tags": [ "developer" ], "summary": "Upsert a contact", "description": "Create or update a contact (lead) in your account. If the phone number already exists, only provided fields are overwritten — blank/omitted fields are left unchanged. Tags are merged (union). Notes are appended.\n\n**Requires** `X-API-Key` header with your developer API key.\n\nUse this endpoint from any CRM (HubSpot, Salesforce, Zoho, Pipedrive) or automation tool (Make, Zapier, n8n) that can make HTTP POST requests.", "operationId": "upsert_contact_api_developer_v1_contacts_post", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpsertRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpsertResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/contacts/bulk": { "post": { "tags": [ "developer" ], "summary": "Bulk upsert contacts", "description": "Upsert up to 100 contacts in a single request. Same upsert rules as the single-contact endpoint — partial failures do not abort the batch.\n\n**Requires** `X-API-Key` header.", "operationId": "bulk_upsert_contacts_api_developer_v1_contacts_bulk_post", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkContactUpsertRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkContactUpsertResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/phone-numbers": { "get": { "tags": [ "developer" ], "summary": "List your phone numbers", "description": "Returns the phone numbers assigned to your account. Use the `id` field as `phone_number_id` when creating an agent.\n\n**Requires** `X-API-Key` header.", "operationId": "list_developer_phone_numbers_api_developer_v1_phone_numbers_get", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperPhoneNumberResponse" }, "title": "Response List Developer Phone Numbers Api Developer V1 Phone Numbers Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/tts-config": { "get": { "tags": [ "developer" ], "summary": "List TTS providers, voices and languages", "description": "Returns every enabled TTS provider with its full list of voices and supported languages. Use the `value` field of a voice as `voice`, the `id` field of a language as `tts_language`, and the provider `key` as `tts_provider` when calling `POST /v1/agents`.\n\n**Requires** `X-API-Key` header.", "operationId": "get_developer_tts_config_api_developer_v1_tts_config_get", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperTTSConfigResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/tts/generate": { "post": { "tags": [ "developer" ], "summary": "Generate speech audio (single-shot)", "description": "Synthesise a full script into one audio file in a single request — for audiobooks, IVR prompts, notifications, etc. This is **not** the realtime conversational path; it is optimised for throughput and can take up to a few minutes for long scripts.\n\nDiscover voices with **GET /v1/tts-config** (provider `omnivoice`): use a voice's `value` as `actor` and its `lang` as `language`.\n\n**Returns the raw audio bytes** (`audio/wav` or `audio/L16`). Useful headers: `X-Duration-Seconds`, `X-Cost-Inr`, `X-S3-Url` (a persisted download URL), `X-Request-Id`.\n\n**Billed** by generated audio duration (same rate as the dashboard). Up to 6000 characters per request. **Requires** `X-API-Key` header.", "operationId": "developer_generate_tts_api_developer_v1_tts_generate_post", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperTTSGenerateRequest" } } } }, "responses": { "200": { "description": "Audio file bytes", "content": { "application/json": { "schema": {} }, "audio/wav": {} } }, "400": { "description": "Empty/over-length script or invalid parameters" }, "402": { "description": "Insufficient credits" }, "404": { "description": "Voice profile not found" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "description": "Rate limit exceeded" } } } }, "/api/developer/v1/campaigns": { "post": { "tags": [ "developer" ], "summary": "Create a campaign", "description": "Create an outbound call campaign.\n\n**Request format:** `multipart/form-data` (required because a contact Excel file must be uploaded).\n\n**Excel file format:** `.xlsx` or `.xls`, max 1000 rows. Required column: `Phone Number` (E.164, e.g. +919876543210). Optional columns: `Name`, `Custom Instruction`.\n\n**Scheduling:** provide `start_date_time` (ISO 8601) and `time_zone` (IANA, e.g. `Asia/Kolkata`) to schedule the campaign. Omit both to start immediately.\n\n**Retries:** integer 0–3.\n\n**AI automations** (follow-up, SMS, WhatsApp) are not available via API — they remain disabled.\n\n**Requires** `X-API-Key` header.", "operationId": "create_developer_campaign_api_developer_v1_campaigns_post", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_create_developer_campaign_api_developer_v1_campaigns_post" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperCampaignResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/campaigns/{campaign_id}": { "get": { "tags": [ "developer" ], "summary": "Get campaign status", "description": "Fetch the current status of a campaign created via the API.\n\n**Requires** `X-API-Key` header.", "operationId": "get_developer_campaign_api_developer_v1_campaigns__campaign_id__get", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperCampaignResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "tags": [ "developer" ], "summary": "Update a campaign", "description": "Update an existing campaign's properties. Only provided fields are updated — omitted fields remain unchanged.\n\n**Note:** You cannot update the contact file or agent after creation. Create a new campaign if you need to change these.\n\n**Requires** `X-API-Key` header.", "operationId": "update_developer_campaign_api_developer_v1_campaigns__campaign_id__put", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Body_update_developer_campaign_api_developer_v1_campaigns__campaign_id__put" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperCampaignResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "developer" ], "summary": "Delete a campaign", "description": "Permanently deletes a campaign and all its associated contact rows and call logs.\n\nThis action is **irreversible**. Active campaigns should be paused before deleting.\n\n**Requires** `X-API-Key` header.", "operationId": "delete_developer_campaign_api_developer_v1_campaigns__campaign_id__delete", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/campaigns/{campaign_id}/stats": { "get": { "tags": [ "developer" ], "summary": "Get campaign contact stats", "description": "Returns a breakdown of all contacts in the campaign by their current call status.\n\nUseful for polling progress: keep calling until `pending + in_progress == 0`.\n\n**Requires** `X-API-Key` header.", "operationId": "get_developer_campaign_stats_api_developer_v1_campaigns__campaign_id__stats_get", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperCampaignStatsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/campaigns/{campaign_id}/pause": { "patch": { "tags": [ "developer" ], "summary": "Pause a campaign", "description": "Pauses an **active** campaign. The dialer stops picking new contacts; any call already in-flight completes normally.\n\nOnly valid when the campaign is currently `active`.\n\n**Requires** `X-API-Key` header.", "operationId": "pause_developer_campaign_api_developer_v1_campaigns__campaign_id__pause_patch", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperCampaignActionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/campaigns/{campaign_id}/resume": { "patch": { "tags": [ "developer" ], "summary": "Resume a paused campaign", "description": "Resumes a **paused** campaign. The dialer picks up from where it left off.\n\nOnly valid when the campaign is currently `paused`.\n\n**Requires** `X-API-Key` header.", "operationId": "resume_developer_campaign_api_developer_v1_campaigns__campaign_id__resume_patch", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperCampaignActionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/knowledge": { "get": { "tags": [ "developer" ], "summary": "List knowledge bases", "description": "Returns all knowledge bases belonging to your account.\n\nUse the `id` field when attaching knowledge bases to agents.\n\n**Requires** `X-API-Key` header.", "operationId": "list_developer_knowledge_bases_api_developer_v1_knowledge_get", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperKnowledgeBaseResponse" }, "title": "Response List Developer Knowledge Bases Api Developer V1 Knowledge Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "developer" ], "summary": "Create a knowledge base", "description": "Create a new knowledge base. Knowledge bases can be attached to agents to provide context and information during conversations.\n\n**Requires** `X-API-Key` header.", "operationId": "create_developer_knowledge_base_api_developer_v1_knowledge_post", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperKnowledgeBaseCreateRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperKnowledgeBaseResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/knowledge/{knowledge_id}": { "get": { "tags": [ "developer" ], "summary": "Get a knowledge base", "description": "Fetch a single knowledge base by ID.\n\n**Requires** `X-API-Key` header.", "operationId": "get_developer_knowledge_base_api_developer_v1_knowledge__knowledge_id__get", "parameters": [ { "name": "knowledge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Knowledge Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperKnowledgeBaseResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "developer" ], "summary": "Update a knowledge base", "description": "Update an existing knowledge base. Only provided fields are updated — omitted fields remain unchanged.\n\n**Requires** `X-API-Key` header.", "operationId": "update_developer_knowledge_base_api_developer_v1_knowledge__knowledge_id__patch", "parameters": [ { "name": "knowledge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Knowledge Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperKnowledgeBaseUpdateRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperKnowledgeBaseResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "developer" ], "summary": "Delete a knowledge base", "description": "Permanently delete a knowledge base. This action is **irreversible**.\n\n**Note:** Agents currently using this knowledge base will continue to work but will no longer have access to this information.\n\n**Requires** `X-API-Key` header.", "operationId": "delete_developer_knowledge_base_api_developer_v1_knowledge__knowledge_id__delete", "parameters": [ { "name": "knowledge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Knowledge Id" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/widget/session": { "post": { "tags": [ "developer" ], "summary": "Create a widget session token", "description": "Exchange your API key for a short-lived, single-use session token that the browser widget uses to open a WebSocket connection.\n\n**Call this from your server or widget loader script — never expose your API key in browser JavaScript.**\n\nValidations performed:\n- API key is valid and active\n- `agent_id` belongs to your account\n- `origin` is in your `allowed_origins` list (or list is empty)\n- Your account has sufficient credits\n- You are within your daily session limit\n\nThe returned `session_token` is valid for 5 minutes and can only be used once.", "operationId": "create_widget_session_api_developer_v1_widget_session_post", "parameters": [ { "name": "Origin", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin" } }, { "name": "X-Forwarded-For", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Forwarded-For" } }, { "name": "X-Real-IP", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "X-Real-Ip" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetSessionRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetSessionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/widget/config": { "put": { "tags": [ "developer" ], "summary": "Update widget configuration", "description": "Set the allowed origins and session limits for your embedded widget.\n\n**`allowed_origins`**: List of exact origins (scheme + host + optional port) that are permitted to create widget sessions, e.g. `['https://mysite.com']`. An empty list allows all origins — **only use this for local development**.\n\n**`max_session_minutes`**: Hard cap on session duration (1–60 min). The pipeline will force-end the call at this limit regardless of agent settings.\n\n**`max_daily_sessions`**: Rolling 24-hour cap on total widget sessions across all visitors. Set to 0 for unlimited.\n\n**Requires** `X-API-Key` header.", "operationId": "update_widget_config_api_developer_v1_widget_config_put", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetConfigRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetConfigResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "tags": [ "developer" ], "summary": "Get widget configuration", "description": "Returns your current widget configuration. **Requires** `X-API-Key` header.", "operationId": "get_widget_config_api_developer_v1_widget_config_get", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetConfigResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/developer/v1/widget/embed-snippet": { "get": { "tags": [ "developer" ], "summary": "Get widget embed snippet", "description": "Returns the complete HTML snippet to embed the voice widget on your website.\n\n**Usage:**\n1. Call this endpoint with your API key\n2. Copy the returned HTML snippet\n3. Paste it before the closing `` tag on your website\n\n**Requires** `X-API-Key` header (widget key or developer key).", "operationId": "get_widget_embed_snippet_api_developer_v1_widget_embed_snippet_get", "parameters": [ { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Agent Id" } }, { "name": "widget_key", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Widget Key" } }, { "name": "X-API-Key", "in": "header", "required": true, "schema": { "type": "string", "title": "X-Api-Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetEmbedSnippetResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "DeveloperAgentResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "phone_number_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number Id" }, "tts_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tts Provider" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice" }, "tts_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tts Language" }, "greeting_line": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Greeting Line" }, "agent_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Prompt" }, "analysis_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Analysis Prompt" }, "transcription_languages": { "items": { "type": "string" }, "type": "array", "title": "Transcription Languages", "default": [] }, "knowledge_base_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Knowledge Base Ids" }, "allow_interruptions": { "type": "boolean", "title": "Allow Interruptions", "default": false }, "background_music": { "type": "boolean", "title": "Background Music", "default": false }, "hard_end_call_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Hard End Call Minutes" }, "is_active": { "type": "boolean", "title": "Is Active", "default": true }, "enable_video_avatar": { "type": "boolean", "title": "Enable Video Avatar", "default": false }, "simli_face_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Simli Face Id" }, "created_at": { "type": "string", "title": "Created At" }, "greeting_audio_generated": { "type": "boolean", "title": "Greeting Audio Generated", "description": "True if greeting audio was successfully pre-generated", "default": false } }, "type": "object", "required": [ "id", "name", "created_at" ], "title": "DeveloperAgentResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "DeveloperAgentCreateRequest": { "properties": { "name": { "type": "string", "title": "Name", "description": "Agent display name (required)" }, "phone_number_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number Id", "description": "ID from GET /v1/phone-numbers — the number this agent dials from" }, "tts_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tts Provider", "description": "TTS provider key from GET /v1/tts-config. Omit to use your account default." }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice", "description": "Voice value from GET /v1/tts-config for the chosen provider" }, "tts_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tts Language", "description": "Language id from GET /v1/tts-config for the chosen provider" }, "greeting_line": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Greeting Line", "description": "Opening sentence spoken when the call connects. Triggers audio pre-generation." }, "agent_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Prompt", "description": "System prompt that defines the agent's persona, goal and behaviour" }, "analysis_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Analysis Prompt", "description": "Post-call analysis prompt. Must be provided manually — auto-generation is not available via API." }, "transcription_languages": { "items": { "type": "string" }, "type": "array", "title": "Transcription Languages", "description": "STT language codes, e.g. ['en-IN', 'hi-IN']" }, "knowledge_base_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Knowledge Base Ids", "description": "Knowledge base IDs to attach to this agent" }, "allow_interruptions": { "type": "boolean", "title": "Allow Interruptions", "description": "Allow caller to interrupt the agent mid-sentence", "default": false }, "background_music": { "type": "boolean", "title": "Background Music", "description": "Play hold music during pauses", "default": false }, "hard_end_call_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Hard End Call Minutes", "description": "Force-end the call after this many minutes" } }, "type": "object", "required": [ "name" ], "title": "DeveloperAgentCreateRequest" }, "DeveloperAgentUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Agent display name" }, "phone_number_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number Id", "description": "ID from GET /v1/phone-numbers" }, "tts_provider": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tts Provider", "description": "TTS provider key" }, "voice": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice", "description": "Voice value" }, "tts_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tts Language", "description": "Language id" }, "greeting_line": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Greeting Line", "description": "Opening sentence" }, "agent_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Prompt", "description": "System prompt" }, "analysis_prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Analysis Prompt", "description": "Post-call analysis prompt" }, "transcription_languages": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Transcription Languages", "description": "STT language codes" }, "knowledge_base_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Knowledge Base Ids", "description": "Knowledge base IDs" }, "allow_interruptions": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Allow Interruptions", "description": "Allow interruptions" }, "background_music": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Background Music", "description": "Play hold music" }, "hard_end_call_minutes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Hard End Call Minutes", "description": "Force-end after N minutes" }, "enable_video_avatar": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enable Video Avatar", "description": "Enable Simli video avatar" }, "simli_face_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Simli Face Id", "description": "Simli face ID for video avatar" } }, "type": "object", "title": "DeveloperAgentUpdateRequest", "description": "Request model for updating an agent - all fields optional." }, "AgentToggleResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "is_active": { "type": "boolean", "title": "Is Active" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "id", "is_active", "message" ], "title": "AgentToggleResponse", "description": "Response model for agent toggle." }, "DeveloperCallRequest": { "properties": { "agent_id": { "type": "string", "title": "Agent Id", "description": "ID of the agent to use for this call" }, "to_number": { "type": "string", "title": "To Number", "description": "E.164 destination phone number, e.g. +919876543210" }, "contact_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Name", "description": "Name of the contact being called" }, "custom_instruction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom Instruction", "description": "Per-call instruction injected into the agent system prompt" } }, "type": "object", "required": [ "agent_id", "to_number" ], "title": "DeveloperCallRequest" }, "DeveloperCallResponse": { "properties": { "call_id": { "type": "string", "title": "Call Id", "description": "TestCall document ID" }, "status": { "type": "string", "title": "Status", "description": "Initial call status (queued)" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "call_id", "status", "message" ], "title": "DeveloperCallResponse" }, "DeveloperCallLogsResponse": { "properties": { "calls": { "items": { "$ref": "#/components/schemas/DeveloperCallLogItem" }, "type": "array", "title": "Calls" }, "total": { "type": "integer", "title": "Total" }, "page": { "type": "integer", "title": "Page" }, "pages": { "type": "integer", "title": "Pages" } }, "type": "object", "required": [ "calls", "total", "page", "pages" ], "title": "DeveloperCallLogsResponse" }, "CallStatsResponse": { "properties": { "total_calls": { "type": "integer", "title": "Total Calls", "description": "Total number of calls" }, "success_rate": { "type": "number", "title": "Success Rate", "description": "Success rate as percentage (0-100)" }, "average_duration_seconds": { "type": "integer", "title": "Average Duration Seconds", "description": "Average call duration in seconds" }, "total_cost_usd": { "type": "string", "title": "Total Cost Usd", "description": "Total cost in USD" }, "calls_by_status": { "additionalProperties": true, "type": "object", "title": "Calls By Status", "description": "Breakdown by status" } }, "type": "object", "required": [ "total_calls", "success_rate", "average_duration_seconds", "total_cost_usd", "calls_by_status" ], "title": "CallStatsResponse", "description": "Response model for call statistics." }, "CallCancelResponse": { "properties": { "call_id": { "type": "string", "title": "Call Id" }, "status": { "type": "string", "title": "Status" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "call_id", "status", "message" ], "title": "CallCancelResponse", "description": "Response model for call cancellation." }, "BulkCallRequest": { "properties": { "agent_id": { "type": "string", "title": "Agent Id", "description": "Agent ID to use for all calls" }, "calls": { "items": { "$ref": "#/components/schemas/DeveloperCallRequest" }, "type": "array", "maxItems": 100, "title": "Calls", "description": "List of calls to initiate (max 100)" } }, "type": "object", "required": [ "agent_id", "calls" ], "title": "BulkCallRequest", "description": "Request model for bulk call initiation." }, "BulkCallResponse": { "properties": { "success": { "type": "integer", "title": "Success", "description": "Number of successfully queued calls" }, "failed": { "type": "integer", "title": "Failed", "description": "Number of failed calls" }, "results": { "items": { "$ref": "#/components/schemas/BulkCallResult" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "success", "failed", "results" ], "title": "BulkCallResponse", "description": "Response model for bulk call initiation." }, "ContactUpsertRequest": { "properties": { "phone_number": { "type": "string", "title": "Phone Number", "description": "E.164 format, e.g. +919876543210" }, "contact_name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Contact Name" }, "email": { "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ], "title": "Email" }, "city": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "title": "City" }, "location": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Location" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source", "description": "Lead source. Defaults to 'crm_webhook'.", "default": "crm_webhook" }, "lead_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lead Status", "description": "Lead status. Defaults to 'new'.", "default": "new" }, "custom_instruction": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Custom Instruction", "description": "Per-contact instruction injected into the agent system prompt when calling this contact" }, "tags": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Tags", "description": "Tags to merge into this contact (union — never replaces existing tags)" }, "note": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Note", "description": "A note to append to this contact's history" } }, "type": "object", "required": [ "phone_number" ], "title": "ContactUpsertRequest" }, "ContactUpsertResponse": { "properties": { "phone_number": { "type": "string", "title": "Phone Number" }, "created": { "type": "boolean", "title": "Created", "description": "True if this was a new contact, False if an existing contact was updated" }, "contact_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Contact Name" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Location" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Source" }, "lead_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lead Status" } }, "type": "object", "required": [ "phone_number", "created" ], "title": "ContactUpsertResponse" }, "BulkContactUpsertRequest": { "properties": { "contacts": { "items": { "$ref": "#/components/schemas/ContactUpsertRequest" }, "type": "array", "maxItems": 100, "title": "Contacts", "description": "Array of contacts to upsert (max 100)" } }, "type": "object", "required": [ "contacts" ], "title": "BulkContactUpsertRequest" }, "BulkContactUpsertResponse": { "properties": { "success": { "type": "integer", "title": "Success" }, "failed": { "type": "integer", "title": "Failed" }, "results": { "items": { "$ref": "#/components/schemas/ContactUpsertResponse" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "success", "failed", "results" ], "title": "BulkContactUpsertResponse" }, "DeveloperPhoneNumberResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "phone_number": { "type": "string", "title": "Phone Number" }, "provider": { "type": "string", "title": "Provider" }, "is_active": { "type": "boolean", "title": "Is Active" } }, "type": "object", "required": [ "id", "phone_number", "provider", "is_active" ], "title": "DeveloperPhoneNumberResponse", "description": "Minimal phone number info needed to create an agent." }, "DeveloperTTSConfigResponse": { "properties": { "providers": { "items": { "$ref": "#/components/schemas/DeveloperTTSProvider" }, "type": "array", "title": "Providers" } }, "type": "object", "required": [ "providers" ], "title": "DeveloperTTSConfigResponse" }, "DeveloperTTSGenerateRequest": { "properties": { "text": { "type": "string", "title": "Text", "description": "Script to synthesise. Up to 6000 characters per request." }, "actor": { "type": "string", "title": "Actor", "description": "Voice `value` from GET /v1/tts-config (provider 'omnivoice')" }, "language": { "type": "string", "title": "Language", "description": "Language `id` for that voice from GET /v1/tts-config" }, "quality": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Quality", "description": "Quality tier: 'hd' (32 steps, fast) or 'full_hd' (64 steps, best). Overrides num_step.", "default": "hd" }, "num_step": { "type": "integer", "title": "Num Step", "description": "ODE steps 1–64 (used only when `quality` is omitted)", "default": 32 }, "speed": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Speed", "description": "Speaking rate 0.5–2.0. Omit for natural pace." }, "response_format": { "type": "string", "title": "Response Format", "description": "'wav' or 'pcm_s16le'", "default": "wav" }, "sample_rate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Sample Rate", "description": "Output sample rate (8000/16000/24000). Defaults to account setting." } }, "type": "object", "required": [ "text", "actor", "language" ], "title": "DeveloperTTSGenerateRequest" }, "Body_create_developer_campaign_api_developer_v1_campaigns_post": { "properties": { "name": { "type": "string", "title": "Name", "description": "Campaign name" }, "agent_id": { "type": "string", "title": "Agent Id", "description": "Agent ID from GET /v1/agents or the dashboard" }, "contact_file": { "type": "string", "format": "binary", "title": "Contact File", "description": "Excel file (.xlsx/.xls) with Phone Number, Name, Custom Instruction columns" }, "retries": { "type": "string", "title": "Retries", "description": "Number of retry attempts: 0, 1, 2, or 3" }, "phone_number_ids": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number Ids", "description": "JSON array of phone number IDs for multi-number rotation, e.g. '[\"id1\",\"id2\"]'. Max 10." }, "number_rotation_strategy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Number Rotation Strategy", "description": "smart | round_robin | sequential (default: smart)" }, "start_date_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date Time", "description": "ISO 8601 start datetime, e.g. 2026-04-10T09:00:00. Required with time_zone." }, "end_date_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date Time", "description": "ISO 8601 end datetime. Required with time_zone if provided." }, "time_zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Time Zone", "description": "IANA timezone, e.g. Asia/Kolkata or IST. Required when scheduling." }, "custom_first_line": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom First Line", "description": "Custom opening line injected into the agent greeting for every call" } }, "type": "object", "required": [ "name", "agent_id", "contact_file", "retries" ], "title": "Body_create_developer_campaign_api_developer_v1_campaigns_post" }, "DeveloperCampaignResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "agent_id": { "type": "string", "title": "Agent Id" }, "agent_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Name" }, "contact_file_name": { "type": "string", "title": "Contact File Name" }, "total_contacts": { "type": "integer", "title": "Total Contacts", "description": "Number of contacts loaded from the Excel file" }, "retries": { "type": "integer", "title": "Retries" }, "custom_first_line": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom First Line" }, "start_date_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date Time" }, "end_date_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date Time" }, "time_zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Time Zone" }, "status": { "type": "string", "title": "Status", "description": "draft | scheduled | active | completed | stopped" }, "phone_number_ids": { "items": { "type": "string" }, "type": "array", "title": "Phone Number Ids", "default": [] }, "number_rotation_strategy": { "type": "string", "title": "Number Rotation Strategy", "default": "smart" }, "created_at": { "type": "string", "title": "Created At" } }, "type": "object", "required": [ "id", "name", "agent_id", "contact_file_name", "total_contacts", "retries", "status", "created_at" ], "title": "DeveloperCampaignResponse" }, "Body_update_developer_campaign_api_developer_v1_campaigns__campaign_id__put": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name" }, "retries": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Retries" }, "custom_first_line": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Custom First Line" }, "start_date_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date Time" }, "end_date_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date Time" }, "time_zone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Time Zone" }, "phone_number_ids": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone Number Ids" }, "number_rotation_strategy": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Number Rotation Strategy" } }, "type": "object", "title": "Body_update_developer_campaign_api_developer_v1_campaigns__campaign_id__put" }, "DeveloperCampaignStatsResponse": { "properties": { "campaign_id": { "type": "string", "title": "Campaign Id" }, "status": { "type": "string", "title": "Status" }, "total": { "type": "integer", "title": "Total" }, "pending": { "type": "integer", "title": "Pending" }, "in_progress": { "type": "integer", "title": "In Progress" }, "completed": { "type": "integer", "title": "Completed" }, "failed": { "type": "integer", "title": "Failed" }, "no_answer": { "type": "integer", "title": "No Answer" }, "other": { "type": "integer", "title": "Other" } }, "type": "object", "required": [ "campaign_id", "status", "total", "pending", "in_progress", "completed", "failed", "no_answer", "other" ], "title": "DeveloperCampaignStatsResponse" }, "DeveloperCampaignActionResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "status": { "type": "string", "title": "Status" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "id", "status", "message" ], "title": "DeveloperCampaignActionResponse", "description": "Returned after a pause / resume action." }, "DeveloperKnowledgeBaseResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "name": { "type": "string", "title": "Name" }, "text": { "type": "string", "title": "Text" }, "is_active": { "type": "boolean", "title": "Is Active" }, "created_at": { "type": "string", "title": "Created At" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "id", "name", "text", "is_active", "created_at", "updated_at" ], "title": "DeveloperKnowledgeBaseResponse" }, "DeveloperKnowledgeBaseCreateRequest": { "properties": { "name": { "type": "string", "maxLength": 200, "title": "Name", "description": "Knowledge base name" }, "text": { "type": "string", "maxLength": 50000, "title": "Text", "description": "Knowledge base content" }, "is_active": { "type": "boolean", "title": "Is Active", "description": "Whether this knowledge base is active", "default": true } }, "type": "object", "required": [ "name", "text" ], "title": "DeveloperKnowledgeBaseCreateRequest" }, "DeveloperKnowledgeBaseUpdateRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ], "title": "Name", "description": "Knowledge base name" }, "text": { "anyOf": [ { "type": "string", "maxLength": 50000 }, { "type": "null" } ], "title": "Text", "description": "Knowledge base content" }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Active", "description": "Whether this knowledge base is active" } }, "type": "object", "title": "DeveloperKnowledgeBaseUpdateRequest" }, "WidgetSessionRequest": { "properties": { "agent_id": { "type": "string", "title": "Agent Id", "description": "Agent ID the widget will connect to" }, "origin": { "type": "string", "title": "Origin", "description": "The Origin header value of the page embedding the widget, e.g. 'https://mysite.com'. Must match your allowed_origins list (or the list must be empty to allow all origins)." }, "force_audio": { "type": "boolean", "title": "Force Audio", "description": "When true, create an audio-only session even if the agent has video enabled.", "default": false } }, "type": "object", "required": [ "agent_id", "origin" ], "title": "WidgetSessionRequest" }, "WidgetSessionResponse": { "properties": { "session_token": { "type": "string", "title": "Session Token", "description": "Short-lived, single-use token. Pass as ?token= query param when opening the /ws/widget WebSocket. Valid for 5 minutes." }, "expires_in": { "type": "integer", "title": "Expires In", "description": "Seconds until this token expires.", "default": 300 }, "ws_url": { "type": "string", "title": "Ws Url", "description": "Full WebSocket URL to connect to, including the token." }, "video_enabled": { "type": "boolean", "title": "Video Enabled", "description": "Whether video avatar is enabled for this agent.", "default": false }, "simli_face_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Simli Face Id", "description": "Simli face ID if video is enabled." }, "daily_room_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Daily Room Url", "description": "Daily.co room URL for video calls (only if video_enabled=true)." }, "daily_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Daily Token", "description": "Daily.co meeting token for secure access." } }, "type": "object", "required": [ "session_token", "ws_url" ], "title": "WidgetSessionResponse" }, "WidgetConfigRequest": { "properties": { "allowed_origins": { "items": { "type": "string" }, "type": "array", "title": "Allowed Origins", "description": "List of allowed origins, e.g. ['https://mysite.com']. Empty list = allow all origins (development only)." }, "max_session_minutes": { "type": "integer", "maximum": 60, "minimum": 1, "title": "Max Session Minutes", "description": "Maximum session duration in minutes (1–60).", "default": 5 }, "max_daily_sessions": { "type": "integer", "minimum": 0, "title": "Max Daily Sessions", "description": "Max widget sessions per day (0 = unlimited).", "default": 0 } }, "type": "object", "title": "WidgetConfigRequest" }, "WidgetConfigResponse": { "properties": { "allowed_origins": { "items": { "type": "string" }, "type": "array", "title": "Allowed Origins" }, "max_session_minutes": { "type": "integer", "title": "Max Session Minutes" }, "max_daily_sessions": { "type": "integer", "title": "Max Daily Sessions" }, "updated_at": { "type": "string", "title": "Updated At" } }, "type": "object", "required": [ "allowed_origins", "max_session_minutes", "max_daily_sessions", "updated_at" ], "title": "WidgetConfigResponse" }, "WidgetEmbedSnippetResponse": { "properties": { "html_snippet": { "type": "string", "title": "Html Snippet", "description": "Complete HTML snippet to embed on your website" }, "instructions": { "type": "string", "title": "Instructions", "description": "Instructions for embedding the widget" } }, "type": "object", "required": [ "html_snippet", "instructions" ], "title": "WidgetEmbedSnippetResponse", "description": "Response containing the HTML embed snippet for the widget." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "DeveloperCallLogItem": { "properties": { "call_id": { "type": "string", "title": "Call Id" }, "phone_number": { "type": "string", "title": "Phone Number" }, "call_type": { "type": "string", "title": "Call Type", "description": "send_call | campaign | web_test" }, "campaign_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Campaign Id" }, "campaign_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Campaign Name" }, "status": { "type": "string", "title": "Status" }, "duration_seconds": { "type": "integer", "title": "Duration Seconds" }, "cost_usd": { "type": "string", "title": "Cost Usd", "description": "Cost in USD as decimal string" }, "started_at": { "type": "string", "title": "Started At" }, "ended_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ended At" }, "transcript": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transcript" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Summary" }, "sentiment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sentiment" }, "recording_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recording Url" }, "recording_available": { "type": "boolean", "title": "Recording Available" } }, "type": "object", "required": [ "call_id", "phone_number", "call_type", "status", "duration_seconds", "cost_usd", "started_at", "recording_available" ], "title": "DeveloperCallLogItem", "description": "Single entry in the call history list." }, "BulkCallResult": { "properties": { "to_number": { "type": "string", "title": "To Number" }, "call_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Call Id" }, "status": { "type": "string", "title": "Status" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "to_number", "status", "message" ], "title": "BulkCallResult", "description": "Result for a single call in bulk operation." }, "DeveloperTTSProvider": { "properties": { "key": { "type": "string", "title": "Key", "description": "Provider key — pass as tts_provider when creating an agent" }, "label": { "type": "string", "title": "Label", "description": "Human-readable tier label, e.g. 'Standard Voice'" }, "tier": { "type": "string", "title": "Tier", "description": "Billing tier: basic | standard | hd | full_hd" }, "languages": { "items": { "$ref": "#/components/schemas/DeveloperLanguageOption" }, "type": "array", "title": "Languages" }, "voices": { "items": { "$ref": "#/components/schemas/DeveloperVoiceOption" }, "type": "array", "title": "Voices" } }, "type": "object", "required": [ "key", "label", "tier", "languages", "voices" ], "title": "DeveloperTTSProvider" }, "DeveloperLanguageOption": { "properties": { "id": { "type": "string", "title": "Id" }, "label": { "type": "string", "title": "Label" } }, "type": "object", "required": [ "id", "label" ], "title": "DeveloperLanguageOption" }, "DeveloperVoiceOption": { "properties": { "value": { "type": "string", "title": "Value" }, "label": { "type": "string", "title": "Label" }, "lang": { "type": "string", "title": "Lang" } }, "type": "object", "required": [ "value", "label", "lang" ], "title": "DeveloperVoiceOption" } }, "securitySchemes": { "HTTPBearer": { "type": "http", "scheme": "bearer" } } } }