{ "openapi": "3.0.0", "info": { "title": "DialNexa API", "description": "Public `/v1` REST API for the DialNexa voice AI platform.", "version": "1.0.0" }, "servers": [ { "url": "https://api.dialnexa.com", "description": "DialNexa production API" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Agents" }, { "name": "Batch Calls" }, { "name": "Calls" }, { "name": "Knowledge Base" }, { "name": "Languages" }, { "name": "LLMs" }, { "name": "Phone Numbers" }, { "name": "Transcribers" }, { "name": "Webhooks" }, { "name": "Voices" }, { "name": "Workflows" }, { "name": "Workflow Leads" } ], "paths": { "/v1/agents": { "post": { "description": "Creates an agent with its first draft version. Optionally include `agent_functions` and `post_call_analysis` in the body to set them at creation time.\n\n**Phone number fields:** `inbound_phone_number_id` and `outbound_phone_number_id` must belong to the authenticated workspace. On create, these IDs are stored on the draft version. Live dispatch routing is claimed when the version is published through `PATCH /v1/agents/{id}` with `is_published: true`.", "operationId": "createAgent", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" }, "examples": { "request": { "summary": "Create an agent", "value": { "title": "Customer Support Agent", "language_id": "lang_en_in", "voice_id": "voice_abc123", "llm_id": "llm_A1B2C3D4E5F6G7", "transcriber_id": "trs_deepgram_nova_2", "system_prompt_text": "You are a helpful support agent. Confirm the customer issue and summarize next steps.", "fallback_stt_enabled": true, "stt_fallback_transcriber_id": "trs_soniox", "post_call_analysis": [ { "field_name": "issue_type", "field_type": "STRING", "field_description": "Main customer issue discussed on the call" } ], "predictive_preprocessing_enabled": false, "outbound_phone_number_id": "phn_def456", "agent_type": "Single_Prompt_Agent", "prompt_text": "You are a helpful support agent. Confirm the customer's issue and summarize next steps." } } } } } }, "responses": { "201": { "description": "Agent created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agents" }, "examples": { "success": { "summary": "Successful response", "value": { "id": "agent_2g7Xy3tY53gRlp", "folder_id": null, "current_version_number": 1, "timezone": "Asia/Kolkata", "agent_type": "Single_Prompt_Agent", "pipeline_type": "Cascaded", "webhook_id": null, "current_version": { "agent_id": "agent_2g7Xy3tY53gRlp", "version_number": 1, "version_title": "Version 1", "title": "Customer Support Agent", "is_published": false, "language_id": "lang_en_in", "voice_id": "voice_abc123", "llm_id": "llm_A1B2C3D4E5F6G7", "transcriber_id": "trs_deepgram_nova_2", "fallback_stt_enabled": true, "stt_fallback_transcriber_id": "trs_soniox", "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7" }, "versions": [ { "agent_id": "agent_2g7Xy3tY53gRlp", "version_number": 1, "version_title": "Version 1", "title": "Customer Support Agent", "is_published": false, "language_id": "lang_en_in", "voice_id": "voice_abc123", "llm_id": "llm_A1B2C3D4E5F6G7", "transcriber_id": "trs_deepgram_nova_2", "fallback_stt_enabled": true, "stt_fallback_transcriber_id": "trs_soniox", "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Request validation failed", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create Agent", "tags": [ "Agents" ] }, "get": { "description": "Returns all agents for your organization. Agent functions are NOT included in list responses - fetch a specific agent by ID to get its functions.", "operationId": "listAgents", "parameters": [], "responses": { "200": { "description": "Agents returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agents" } } } }, "examples": { "success": { "summary": "Successful response", "value": { "agents": [ { "id": "agent_2g7Xy3tY53gRlp", "folder_id": null, "current_version_number": 1, "timezone": "Asia/Kolkata", "agent_type": "Single_Prompt_Agent", "pipeline_type": "Cascaded", "webhook_id": null, "current_version": { "agent_id": "agent_2g7Xy3tY53gRlp", "version_number": 1, "version_title": "Version 1", "title": "Customer Support Agent", "is_published": false, "language_id": "lang_en_in", "voice_id": "voice_abc123", "llm_id": "llm_A1B2C3D4E5F6G7", "transcriber_id": "trs_deepgram_nova_2", "fallback_stt_enabled": true, "stt_fallback_transcriber_id": "trs_soniox", "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7" }, "versions": [ { "agent_id": "agent_2g7Xy3tY53gRlp", "version_number": 1, "version_title": "Version 1", "title": "Customer Support Agent", "is_published": false, "language_id": "lang_en_in", "voice_id": "voice_abc123", "llm_id": "llm_A1B2C3D4E5F6G7", "transcriber_id": "trs_deepgram_nova_2", "fallback_stt_enabled": true, "stt_fallback_transcriber_id": "trs_soniox", "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7" } ] } ] } } } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid query parameters", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Agents", "tags": [ "Agents" ] } }, "/v1/agents/{id}": { "patch": { "description": "Updates the specified draft version of an agent. `version_number` is required.\n\n**Managing functions via this endpoint:**\n- Pass `agent_functions: [...]` to fully replace all functions for that version.\n- Pass `agent_functions: []` to remove all functions.\n- Omit `agent_functions` entirely to leave existing functions untouched.\n\n**Post-call analysis LLM:**\n- Pass `post_call_analysis_llm_id`, for example `llm_A1B2C3D4E5F6G7`, to set the LLM used for post-call field extraction.\n- Pass `null` to clear the override and revert to the organization default.\n- Omit the field to leave it unchanged.\n\n**Phone number assignment:**\n- `inbound_phone_number_id` and `outbound_phone_number_id` are applied to live routing only when `is_published: true` is included in the same request.\n- Sending a phone number ID without `is_published: true` leaves live routing unchanged.\n- Pass an empty string to detach a phone number while publishing.\n- Outbound changes can return `409 Conflict` when active workflows still use the number. Pause those workflows before retrying.\n\nPublished versions cannot be updated, except to set `is_published: true` to publish a draft.", "operationId": "updateAgent", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Agent ID", "schema": { "example": "agent_2g7Xy3tY53gRlp", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" }, "examples": { "request": { "summary": "Update a draft agent version", "value": { "version_number": 1, "title": "Customer Support Agent", "llm_id": "llm_A1B2C3D4E5F6G7", "fallback_stt_enabled": true, "stt_fallback_transcriber_id": "trs_soniox", "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7" } }, "clearPostCallAnalysisLlm": { "summary": "Clear post-call analysis LLM override", "value": { "version_number": 1, "post_call_analysis_llm_id": null } }, "publishWithOutboundNumber": { "summary": "Publish a draft with an outbound number", "value": { "version_number": 1, "is_published": true, "outbound_phone_number_id": "phn_def456" } }, "detachOutboundNumber": { "summary": "Publish while detaching an outbound number", "value": { "version_number": 2, "is_published": true, "outbound_phone_number_id": "" } } } } } }, "responses": { "200": { "description": "Agent updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agents" }, "examples": { "success": { "summary": "Successful response", "value": { "id": "agent_2g7Xy3tY53gRlp", "folder_id": null, "current_version_number": 1, "timezone": "Asia/Kolkata", "agent_type": "Single_Prompt_Agent", "pipeline_type": "Cascaded", "webhook_id": null, "current_version": { "agent_id": "agent_2g7Xy3tY53gRlp", "version_number": 1, "version_title": "Version 1", "title": "Customer Support Agent", "is_published": false, "language_id": "lang_en_in", "voice_id": "voice_abc123", "llm_id": "llm_A1B2C3D4E5F6G7", "transcriber_id": "trs_deepgram_nova_2", "fallback_stt_enabled": true, "stt_fallback_transcriber_id": "trs_soniox", "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7" }, "versions": [ { "agent_id": "agent_2g7Xy3tY53gRlp", "version_number": 1, "version_title": "Version 1", "title": "Customer Support Agent", "is_published": false, "language_id": "lang_en_in", "voice_id": "voice_abc123", "llm_id": "llm_A1B2C3D4E5F6G7", "transcriber_id": "trs_deepgram_nova_2", "fallback_stt_enabled": true, "stt_fallback_transcriber_id": "trs_soniox", "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7" } ] } } } } } }, "400": { "description": "Invalid body or attempting to update a published version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Request validation failed", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Agent or version not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Agent not found", "error": "Not Found" } } } } } }, "409": { "description": "Phone number assignment conflicts with active workflows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "phoneNumberUsedInActiveWorkflows": { "summary": "409 Conflict", "value": { "statusCode": 409, "message": "Cannot bind outbound_phone_number_id \"phn_def456\" to this agent because it is currently used by active workflows. Pause those workflows first, then retry.", "error": "Conflict" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Update Agent", "tags": [ "Agents" ] }, "delete": { "description": "Deletes an agent and all its versions. Historical call records remain available.", "operationId": "deleteAgent", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Agent ID", "schema": { "example": "agent_2g7Xy3tY53gRlp", "type": "string" } } ], "responses": { "200": { "description": "Agent deleted successfully.", "content": { "application/json": { "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Agent deleted successfully" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Agent deleted successfully" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Agent not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete Agent", "tags": [ "Agents" ] }, "get": { "description": "Returns the agent with all versions. Each version includes `agent_functions`, `pronunciations`, and `postcall_analysis` embedded.", "operationId": "getAgent", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Agent ID", "schema": { "example": "agent_2g7Xy3tY53gRlp", "type": "string" } } ], "responses": { "200": { "description": "Agent returned with all versions and embedded agent_functions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agents" }, "examples": { "success": { "summary": "Successful response", "value": { "id": "agent_2g7Xy3tY53gRlp", "folder_id": null, "current_version_number": 1, "timezone": "Asia/Kolkata", "agent_type": "Single_Prompt_Agent", "pipeline_type": "Cascaded", "webhook_id": null, "current_version": { "agent_id": "agent_2g7Xy3tY53gRlp", "version_number": 1, "version_title": "Version 1", "title": "Customer Support Agent", "is_published": false, "language_id": "lang_en_in", "voice_id": "voice_abc123", "llm_id": "llm_A1B2C3D4E5F6G7", "transcriber_id": "trs_deepgram_nova_2", "fallback_stt_enabled": true, "stt_fallback_transcriber_id": "trs_soniox", "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7" }, "versions": [ { "agent_id": "agent_2g7Xy3tY53gRlp", "version_number": 1, "version_title": "Version 1", "title": "Customer Support Agent", "is_published": false, "language_id": "lang_en_in", "voice_id": "voice_abc123", "llm_id": "llm_A1B2C3D4E5F6G7", "transcriber_id": "trs_deepgram_nova_2", "fallback_stt_enabled": true, "stt_fallback_transcriber_id": "trs_soniox", "post_call_analysis_llm_id": "llm_A1B2C3D4E5F6G7" } ] } } } } } }, "400": { "description": "Invalid agent ID format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid query parameters", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - agent does not belong to your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Agent not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Agent Details", "tags": [ "Agents" ] } }, "/v1/batch-calls": { "post": { "description": "Uploads a CSV or Excel leads file, creates a batch call, and enqueues outbound calls for all leads.", "operationId": "createBatchCall", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "title", "agent_id", "agent_version_number" ], "properties": { "file": { "type": "string", "format": "binary", "description": "CSV or Excel file containing leads (max 10 MB)" }, "title": { "type": "string", "example": "Q3 Follow-up Batch", "maxLength": 35, "description": "Batch title shown in the dashboard. Must be 35 characters or fewer." }, "agent_id": { "type": "string", "example": "agent_abc123" }, "agent_version_number": { "type": "number", "example": 1 }, "starts_at": { "type": "string", "example": "2024-01-15T09:00:00Z", "description": "ISO 8601 datetime - leave empty to start immediately" }, "ends_at": { "type": "string", "example": "2024-01-15T18:00:00Z" }, "calling_hours_start": { "type": "string", "example": "09:00" }, "calling_hours_end": { "type": "string", "example": "18:00" } } }, "examples": { "request": { "summary": "Request example", "value": { "file": "leads.csv", "title": "Q3 Follow-up Batch", "agent_id": "agent_abc123", "agent_version_number": 1 } } } } } }, "responses": { "201": { "description": "Batch call created and calls enqueued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "batch_abc123" }, "title": { "type": "string" }, "total_records": { "type": "number", "example": 250 }, "status": { "type": "string", "example": "initiated" }, "from_number": { "type": "string", "nullable": true }, "warning": { "type": "object", "description": "Non-blocking scheduling warning returned when another running, waiting, or nearby scheduled batch may delay this batch.", "properties": { "message": { "type": "string" }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "running", "waiting", "scheduled" ] }, "batch_name": { "type": "string" }, "processed_leads": { "type": "number" }, "total_leads": { "type": "number" }, "starts_at": { "type": "string", "format": "date-time" } } } } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "id": "batch_abc123", "title": "Q3 Follow-up Batch", "total_records": 250, "status": "initiated", "from_number": "+14155552671", "warning": { "message": "This batch was created, but your organization already has 1 running batch ahead of it. Batches run one at a time per organization, so this batch may be delayed.", "conflicts": [ { "kind": "running", "batch_name": "July renewals", "processed_leads": 42, "total_leads": 250 } ] } } } } } } }, "400": { "description": "Invalid file or missing required fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "The uploaded file must include a phone_number column", "error": "Bad Request" } }, "titleTooLong": { "summary": "Title too long", "value": { "statusCode": 400, "message": "title must be 35 characters or fewer (received 42).", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "Destination country or network prefix is not enabled for this workspace", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create Batch Call", "tags": [ "Batch Calls" ] }, "get": { "operationId": "listBatchCalls", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "example": 20, "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by batch status - can be a single status or comma-separated list. Supported values include draft, waiting, scheduled, running, paused, completed, cancelled, deleted, and legacy active.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch calls returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "batch_abc123" }, "title": { "type": "string" }, "status": { "type": "string" }, "total_records": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "total_lead_count": { "type": "number", "description": "Total recipients loaded into the batch." }, "sent_lead_count": { "type": "number", "description": "Initial recipient calls that have been sent." }, "picked_up_lead_count": { "type": "number", "description": "Calls that connected." }, "number_of_retries": { "type": "number", "nullable": true, "description": "Configured retry count." }, "first_retry_count": { "type": "number", "nullable": true, "description": "Retry call logs scheduled for the first retry depth." }, "second_retry_count": { "type": "number", "nullable": true, "description": "Retry call logs scheduled for the second retry depth." }, "third_retry_count": { "type": "number", "nullable": true, "description": "Retry call logs scheduled for the third retry depth." }, "fourth_retry_count": { "type": "number", "nullable": true, "description": "Retry call logs scheduled for the fourth retry depth." }, "attempt_stages": { "type": "array", "description": "Per-stage attempt progress. Depth 0 is the initial call, and depths 1 through 4 are retry stages. Present when retry enrichment is available.", "items": { "type": "object", "properties": { "depth": { "type": "number", "example": 0 }, "attempted": { "type": "number", "example": 240 }, "total": { "type": "number", "example": 250 } } } } } } }, "total": { "type": "number" }, "page": { "type": "number" }, "limit": { "type": "number" } } }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "batch_abc123", "title": "Q3 Follow-up Batch", "status": "waiting", "total_records": 250, "createdAt": "2026-07-03T10:30:00.000Z", "total_lead_count": 250, "sent_lead_count": 240, "picked_up_lead_count": 120, "number_of_retries": 2, "first_retry_count": 80, "second_retry_count": 25, "third_retry_count": 0, "fourth_retry_count": 0, "attempt_stages": [ { "depth": 0, "attempted": 240, "total": 250 }, { "depth": 1, "attempted": 60, "total": 80 }, { "depth": 2, "attempted": 10, "total": 25 } ] } ], "total": 1, "page": 1, "limit": 20 } } } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid query parameters", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "Destination country or network prefix is not enabled for this workspace", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Batch Calls", "tags": [ "Batch Calls" ], "description": "Returns batch call jobs for the authenticated workspace, including status and progress fields." } }, "/v1/batch-calls/{id}": { "get": { "operationId": "getBatchCall", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Batch call ID", "schema": { "example": "batch_abc123", "type": "string" } }, { "name": "agent_id", "required": false, "in": "query", "description": "Filter by agent ID(s) - can be a single ID or comma-separated list (e.g., 1,2,3)", "schema": { "type": "string" } }, { "name": "call_id", "required": false, "in": "query", "description": "Filter by call ID - can be a single ID or comma-separated list (e.g., call_abc,call_def)", "schema": { "type": "string" } }, { "name": "batch_call_id", "required": false, "in": "query", "description": "Filter by batch call ID - can be a single ID or comma-separated list (e.g., batch_abc,batch_def)", "schema": { "type": "string" } }, { "name": "from", "required": false, "in": "query", "description": "Filter by sender phone number", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "Filter by recipient phone number", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by call type(s) - can be a single value or comma-separated list", "schema": { "type": "string", "enum": [ "phone", "web" ] } }, { "name": "call_direction", "required": false, "in": "query", "description": "Filter by call direction(s) - can be a single value or comma-separated list", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } }, { "name": "latency_min", "required": false, "in": "query", "description": "Filter by minimum latency (in milliseconds)", "schema": { "type": "number" } }, { "name": "latency_max", "required": false, "in": "query", "description": "Filter by maximum latency (in milliseconds)", "schema": { "type": "number" } }, { "name": "agent_version_id", "required": false, "in": "query", "description": "Filter by agent version ID(s) - can be a single ID or comma-separated list (e.g., 1,2,3)", "schema": { "type": "string" } }, { "name": "agent_version_name", "required": false, "in": "query", "description": "Search by agent version name (partial match, case-insensitive)", "schema": { "type": "string" } }, { "name": "sentiment", "required": false, "in": "query", "description": "Filter by sentiment(s) - can be a single value or comma-separated list", "schema": { "type": "string", "enum": [ "positive", "neutral", "negative", "unknown" ] } }, { "name": "start_date", "required": false, "in": "query", "description": "Filter by start date (ISO format)", "schema": { "type": "string" } }, { "name": "end_date", "required": false, "in": "query", "description": "Filter by end date (ISO format)", "schema": { "type": "string" } }, { "name": "duration_greater_than", "required": false, "in": "query", "description": "Filter by minimum call duration (in milliseconds)", "schema": { "type": "number" } }, { "name": "duration_less_than", "required": false, "in": "query", "description": "Filter by maximum call duration (in milliseconds)", "schema": { "type": "number" } }, { "name": "duration_min", "required": false, "in": "query", "description": "Filter by minimum duration range (in milliseconds)", "schema": { "type": "number" } }, { "name": "duration_max", "required": false, "in": "query", "description": "Filter by maximum duration range (in milliseconds)", "schema": { "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "Page number (starts from 1)", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of records per page (min: 1, default: 20, max: 200)", "schema": { "example": 20, "type": "number" } }, { "name": "created_at", "required": false, "in": "query", "description": "Sort by created_at (asc or desc)", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "duration", "required": false, "in": "query", "description": "Sort by duration (asc or desc)", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "status", "required": false, "in": "query", "description": "Filter by call status(es) - can be a single status or comma-separated list", "schema": { "type": "string" } }, { "name": "export", "required": false, "in": "query", "description": "Set to true to export all data without pagination", "schema": { "type": "boolean" } }, { "name": "end_reason", "required": false, "in": "query", "description": "Filter by end/hangup reason - exact match; comma-separate multiple values for OR filtering", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Calls in the batch returned successfully.", "content": { "application/json": { "examples": { "success": { "summary": "Successful response", "value": { "callLogs": [ { "id": "call_abc123", "agent_id": "agent_2g7Xy3tY53gRlp", "to_number": "+919876543210", "from_number": "+14155552671", "status": "initiated", "call_direction": "outbound", "createdAt": "2026-07-03T10:30:00.000Z", "batch_id": "batch_abc123" } ], "total": 1, "page": 1, "limit": 20, "totalPages": 1 } } }, "schema": { "type": "object", "properties": { "callLogs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "call_abc123" }, "status": { "type": "string", "example": "completed" }, "from_number": { "type": "string", "example": "+14155552671" }, "to_number": { "type": "string", "example": "+919876543210" }, "duration": { "type": "number", "example": 42 }, "createdAt": { "type": "string", "format": "date-time" } } } }, "total": { "type": "number" }, "page": { "type": "number" }, "limit": { "type": "number" }, "totalPages": { "type": "number" } } } } } }, "400": { "description": "Invalid batch call ID format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid batch call ID format", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "Destination country or network prefix is not enabled for this workspace", "error": "Forbidden" } } } } } }, "404": { "description": "Batch call not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Batch call not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Batch Call Details", "tags": [ "Batch Calls" ], "description": "Returns one batch call job and its current processing details." } }, "/v1/batch-calls/{id}/status": { "patch": { "operationId": "updateBatchCallStatus", "summary": "Update Batch Call Status", "description": "Changes the execution status of a batch call. Use `pause` to halt new outbound calls, `resume` to continue a paused batch, or `cancel` to permanently stop the batch and remove queued calls.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Batch call ID", "schema": { "example": "batch_abc123", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "pause", "resume", "cancel" ], "example": "pause", "description": "The status transition to apply." } } }, "examples": { "pause": { "summary": "Pause a batch call", "value": { "action": "pause" } }, "resume": { "summary": "Resume a batch call", "value": { "action": "resume" } }, "cancel": { "summary": "Cancel a batch call", "value": { "action": "cancel" } } } } } }, "responses": { "200": { "description": "Batch call status updated successfully.", "content": { "application/json": { "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Campaign paused successfully", "campaign": { "id": "batch_abc123", "status": "paused", "title": "Q3 Follow-up Batch" }, "affectedCalls": { "initiated": 0, "queued": 0, "removedFromQueue": 12, "cancelledCallLogs": 0, "resumedCallLogs": 0 } } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Campaign paused successfully" }, "campaign": { "type": "object", "properties": { "id": { "type": "string", "example": "batch_abc123" }, "status": { "type": "string", "enum": [ "initiated", "draft", "waiting", "scheduled", "running", "paused", "completed", "cancelled", "deleted" ], "example": "paused" }, "title": { "type": "string", "example": "Q3 Follow-up Batch" } } }, "affectedCalls": { "type": "object", "properties": { "initiated": { "type": "number", "example": 0 }, "queued": { "type": "number", "example": 0 }, "removedFromQueue": { "type": "number", "example": 12 }, "cancelledCallLogs": { "type": "number", "example": 0 }, "resumedCallLogs": { "type": "number", "example": 0 } } } } } } } }, "400": { "description": "Invalid action, or action not allowed for the current batch call status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid action. Must be one of: pause, resume, cancel", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - batch call does not belong to your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Batch call not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Batch call not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Batch Calls" ] } }, "/v1/calls": { "post": { "description": "Schedules a single outbound call. The call is queued and initiated when resources are available.", "operationId": "createCall", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCallRequest" }, "examples": { "request": { "summary": "Create an outbound call", "value": { "agent_id": "agent_2g7Xy3tY53gRlp", "phone_number": "+919876543210", "agent_version_number": 1, "metadata": {} } } } } } }, "responses": { "201": { "description": "Call created and queued successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCallResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "id": "call_abc123", "to_phone_number": "+919876543210", "agent_id": "agent_2g7Xy3tY53gRlp", "agent_version_number": 1 } } } } } }, "400": { "description": "Invalid request body - missing required fields or validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "phone_number must be a valid E.164 phone number", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "402": { "description": "Payment required - insufficient billing wallet balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "402 Payment Required", "value": { "statusCode": 402, "message": "Insufficient billing wallet balance", "error": "Payment Required" } } } } } }, "403": { "description": "Forbidden - KYC not verified or API key does not have access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "Destination country or network prefix is not enabled for this workspace", "error": "Forbidden" } } } } } }, "404": { "description": "Agent or phone number not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Agent or phone number not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create Call", "tags": [ "Calls" ] }, "get": { "operationId": "listCalls", "parameters": [ { "name": "agent_id", "required": false, "in": "query", "description": "Filter by agent ID(s) - can be a single ID or comma-separated list (e.g., 1,2,3)", "schema": { "type": "string" } }, { "name": "call_id", "required": false, "in": "query", "description": "Filter by call ID - can be a single ID or comma-separated list (e.g., call_abc,call_def)", "schema": { "type": "string" } }, { "name": "batch_call_id", "required": false, "in": "query", "description": "Filter by batch call ID - can be a single ID or comma-separated list (e.g., batch_abc,batch_def)", "schema": { "type": "string" } }, { "name": "from", "required": false, "in": "query", "description": "Filter by sender phone number", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "Filter by recipient phone number", "schema": { "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Filter by call type(s) - can be a single value or comma-separated list", "schema": { "type": "string", "enum": [ "phone", "web" ] } }, { "name": "call_direction", "required": false, "in": "query", "description": "Filter by call direction(s) - can be a single value or comma-separated list", "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } }, { "name": "latency_min", "required": false, "in": "query", "description": "Filter by minimum latency (in milliseconds)", "schema": { "type": "number" } }, { "name": "latency_max", "required": false, "in": "query", "description": "Filter by maximum latency (in milliseconds)", "schema": { "type": "number" } }, { "name": "agent_version_id", "required": false, "in": "query", "description": "Filter by agent version ID(s) - can be a single ID or comma-separated list (e.g., 1,2,3)", "schema": { "type": "string" } }, { "name": "agent_version_name", "required": false, "in": "query", "description": "Search by agent version name (partial match, case-insensitive)", "schema": { "type": "string" } }, { "name": "sentiment", "required": false, "in": "query", "description": "Filter by sentiment(s) - can be a single value or comma-separated list", "schema": { "type": "string", "enum": [ "positive", "neutral", "negative", "unknown" ] } }, { "name": "start_date", "required": false, "in": "query", "description": "Filter by start date (ISO format)", "schema": { "type": "string" } }, { "name": "end_date", "required": false, "in": "query", "description": "Filter by end date (ISO format)", "schema": { "type": "string" } }, { "name": "duration_greater_than", "required": false, "in": "query", "description": "Filter by minimum call duration (in milliseconds)", "schema": { "type": "number" } }, { "name": "duration_less_than", "required": false, "in": "query", "description": "Filter by maximum call duration (in milliseconds)", "schema": { "type": "number" } }, { "name": "duration_min", "required": false, "in": "query", "description": "Filter by minimum duration range (in milliseconds)", "schema": { "type": "number" } }, { "name": "duration_max", "required": false, "in": "query", "description": "Filter by maximum duration range (in milliseconds)", "schema": { "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "Page number (starts from 1)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of records per page (min: 1, default: 20, max: 200)", "schema": { "type": "string" } }, { "name": "created_at", "required": false, "in": "query", "description": "Sort by created_at (asc or desc)", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "duration", "required": false, "in": "query", "description": "Sort by duration (asc or desc)", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "status", "required": false, "in": "query", "description": "Filter by call status(es) - can be a single status or comma-separated list", "schema": { "type": "string" } }, { "name": "export", "required": false, "in": "query", "description": "Set to true to export all data without pagination", "schema": { "type": "boolean" } }, { "name": "end_reason", "required": false, "in": "query", "description": "Filter by end/hangup reason - exact match; comma-separate multiple values for OR filtering", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Calls returned successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CallLogs" } }, "examples": { "success": { "summary": "Successful response", "value": [ { "id": "call_abc123", "agent_id": "agent_2g7Xy3tY53gRlp", "to_number": "+919876543210", "from_number": "+14155552671", "status": "initiated", "call_direction": "outbound", "createdAt": "2026-07-03T10:30:00.000Z", "duration": 42, "end_reason": "completed" } ] } } } } }, "400": { "description": "Bad request - invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid query parameters", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "Destination country or network prefix is not enabled for this workspace", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Calls", "tags": [ "Calls" ], "description": "Returns calls for the authenticated workspace using the supplied filters, newest records first." } }, "/v1/calls/{id}": { "get": { "operationId": "getCall", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Call ID", "schema": { "example": "call_abc123", "type": "string" } } ], "responses": { "200": { "description": "Call returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallLogs" }, "examples": { "success": { "summary": "Successful response", "value": { "id": "call_abc123", "agent_id": "agent_2g7Xy3tY53gRlp", "to_number": "+919876543210", "from_number": "+14155552671", "status": "initiated", "call_direction": "outbound", "createdAt": "2026-07-03T10:30:00.000Z", "duration": 42, "transcript": "Agent: Hello Priya. User: I am interested in the loan offer.", "summary": "Customer asked for details about the loan offer." } } } } } }, "400": { "description": "Invalid call ID format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid call ID format", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - call does not belong to your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this call", "error": "Forbidden" } } } } } }, "404": { "description": "Call not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Call not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Call Details", "tags": [ "Calls" ], "description": "Returns the current call record, including routing, status, transcript, and analysis fields when available." } }, "/v1/knowledge-base": { "post": { "operationId": "createKnowledgeBase", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeBaseRequest" }, "examples": { "request": { "summary": "Request example", "value": { "name": "Product Documentation" } } } } } }, "responses": { "201": { "description": "Knowledge base created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBase" }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_abc123", "name": "Loan FAQ", "description": "Frequently asked questions for loan calls", "file_name": "loan-faq.pdf", "status": "ready", "createdAt": "2026-07-03T10:30:00.000Z" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "409": { "description": "Knowledge base name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "409 Conflict", "value": { "statusCode": 409, "message": "Knowledge base with this name already exists", "error": "Conflict" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create Knowledge Base", "tags": [ "Knowledge Base" ], "description": "Creates an empty knowledge base that can be populated and attached to agent versions." }, "get": { "operationId": "listKnowledgeBases", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 20, "type": "number" } }, { "name": "sortBy", "required": false, "in": "query", "schema": { "example": "id", "type": "string" } }, { "name": "sortOrder", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "Knowledge bases returned successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "meta" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBase" } }, "meta": { "type": "object", "required": [ "totalItems", "itemsPerPage", "totalPages", "currentPage" ], "properties": { "totalItems": { "type": "integer", "example": 1 }, "itemsPerPage": { "type": "integer", "example": 20 }, "totalPages": { "type": "integer", "example": 1 }, "currentPage": { "type": "integer", "example": 1 } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "kb_abc123", "name": "Loan FAQ" } ], "meta": { "totalItems": 1, "itemsPerPage": 20, "totalPages": 1, "currentPage": 1 } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Knowledge Bases", "tags": [ "Knowledge Base" ], "description": "Returns knowledge bases for the authenticated workspace in an items and meta pagination envelope." } }, "/v1/knowledge-base/{id}": { "patch": { "operationId": "updateKnowledgeBase", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKnowledgeBaseRequest" }, "examples": { "request": { "summary": "Update a knowledge base", "value": { "name": "Updated Loan FAQ" } } } } } }, "responses": { "200": { "description": "Knowledge base updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBase" }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_abc123", "name": "Updated Loan FAQ", "description": "Frequently asked questions for loan calls", "file_name": "loan-faq.pdf", "status": "ready", "createdAt": "2026-07-03T10:30:00.000Z" } } } } } }, "409": { "description": "New name already in use in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "409 Conflict", "value": { "statusCode": 409, "message": "Knowledge base with this name already exists", "error": "Conflict" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Update Knowledge Base", "tags": [ "Knowledge Base" ], "description": "Renames one knowledge base without changing its ID or agent attachments." }, "delete": { "operationId": "deleteKnowledgeBase", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Knowledge base deleted successfully.", "content": { "application/json": { "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Knowledge base deleted successfully" } } }, "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Knowledge base deleted successfully" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - knowledge base does not belong to your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Knowledge base not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Knowledge base not found", "error": "Not Found" } } } } } }, "409": { "description": "Knowledge base is still used by one or more agents.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" } ], "properties": { "agent_ids": { "type": "array", "items": { "type": "string" }, "example": [ "agent_2g7Xy3tY53gRlp" ] } } }, "examples": { "knowledgeBaseInUse": { "summary": "409 Conflict", "value": { "statusCode": 409, "message": "This knowledge base cannot be deleted because it is being used by 1 agent(s): agent_2g7Xy3tY53gRlp. Please unlink it from these agents before deleting.", "agent_ids": [ "agent_2g7Xy3tY53gRlp" ], "error": "Conflict" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete Knowledge Base", "tags": [ "Knowledge Base" ], "description": "Deletes a knowledge base. The request is blocked while an agent still uses it." }, "get": { "operationId": "getKnowledgeBase", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Knowledge base returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBase" }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_abc123", "name": "Loan FAQ", "description": "Frequently asked questions for loan calls", "file_name": "loan-faq.pdf", "status": "ready", "createdAt": "2026-07-03T10:30:00.000Z" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Knowledge Base Details", "tags": [ "Knowledge Base" ], "description": "Returns one knowledge base owned by the authenticated workspace." } }, "/v1/languages": { "get": { "operationId": "listLanguages", "parameters": [], "responses": { "200": { "description": "Languages returned successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Languages" } }, "examples": { "success": { "summary": "Successful response", "value": [ { "id": "lang_en_in", "name": "English (India)", "code": "en-IN" } ] } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Languages", "tags": [ "Languages" ], "description": "Returns the complete catalog of languages available for agent configuration." } }, "/v1/languages/{id}": { "get": { "operationId": "getLanguage", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Language ID", "schema": { "example": "lang_abc123", "type": "string" } } ], "responses": { "200": { "description": "Language returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Languages" }, "examples": { "success": { "summary": "Successful response", "value": { "id": "lang_en_in", "name": "English (India)", "code": "en-IN" } } } } } }, "400": { "description": "Invalid catalog ID format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid catalog ID format", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Language not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Language not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Language Details", "tags": [ "Languages" ], "description": "Returns one language catalog record by ID." } }, "/v1/llms": { "get": { "operationId": "listLlms", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 20, "type": "number" } }, { "name": "sortBy", "required": false, "in": "query", "schema": { "example": "id", "type": "string" } }, { "name": "sortOrder", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "LLMs returned successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Llm" } }, "examples": { "success": { "summary": "Successful response", "value": [ { "id": "llm_A1B2C3D4E5F6G7", "name": "GPT-4.1 Mini", "provider": "openai", "supports_structured_output": true } ] } } } } }, "400": { "description": "Bad request - invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid query parameters", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List LLMs", "tags": [ "LLMs" ], "description": "Returns the complete catalog of large language models available for agent configuration." } }, "/v1/llms/fallback": { "get": { "operationId": "listFallbackLlms", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 20, "type": "number" } }, { "name": "sortBy", "required": false, "in": "query", "schema": { "example": "id", "type": "string" } }, { "name": "sortOrder", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } } ], "responses": { "200": { "description": "Fallback LLM returned successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Llm" } }, "examples": { "success": { "summary": "Successful response", "value": [] } } } } }, "400": { "description": "Bad request - invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid query parameters", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Fallback LLMs", "tags": [ "LLMs" ], "description": "Returns large language models that can be selected as fallback models." } }, "/v1/llms/{id}": { "get": { "operationId": "getLlm", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "LLM ID", "schema": { "example": "llm_abc123", "type": "string" } } ], "responses": { "200": { "description": "LLM returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Llm" }, "examples": { "success": { "summary": "Successful response", "value": { "id": "llm_A1B2C3D4E5F6G7", "name": "GPT-4.1 Mini", "provider": "openai", "supports_structured_output": true } } } } } }, "400": { "description": "Invalid catalog ID format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid catalog ID format", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "LLM not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "LLM not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get LLM Details", "tags": [ "LLMs" ], "description": "Returns one large language model catalog record by ID." } }, "/v1/organization-phone-numbers": { "get": { "operationId": "listPhoneNumbers", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "example": 20, "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } } ], "responses": { "200": { "description": "Phone numbers returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "phn_abc123" }, "phone_number": { "type": "string", "example": "+919876543210" }, "provider": { "type": "string" }, "status": { "type": "string" } } } }, "total": { "type": "number" }, "page": { "type": "number" }, "limit": { "type": "number" } } }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "phn_abc123", "phone_number": "+14155552671", "provider": "plivo", "status": "active", "country_code": "US", "nickname": "US Sales Line" } ], "total": 1, "page": 1, "limit": 20 } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Phone Numbers", "tags": [ "Phone Numbers" ], "description": "Returns phone numbers owned by the authenticated workspace with pagination metadata." } }, "/v1/organization-phone-numbers/plivo-numbers": { "get": { "description": "Searches available Plivo phone numbers that match the supplied filters.", "operationId": "searchAvailablePhoneNumbers", "parameters": [ { "name": "country_iso", "required": true, "in": "query", "description": "ISO country code (e.g., US, GB, CA)", "schema": { "example": "US", "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Type of number (e.g., tollfree, local, mobile)", "schema": { "example": "tollfree", "type": "string" } } ], "responses": { "200": { "description": "Available Plivo numbers returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailablePhoneNumbersResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "api_id": "9f6d7c", "objects": [ { "number": "+14155552671", "type": "local", "monthly_rental_rate": "0.80", "setup_rate": "0.00", "voice_enabled": true, "sms_enabled": true, "mms_enabled": false, "country_iso": "US", "number_format": "+14155552671" } ], "meta": { "total_count": 1 } } } } } } }, "400": { "description": "country_iso is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "country_iso is required", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Search Plivo Numbers", "tags": [ "Phone Numbers" ] } }, "/v1/organization-phone-numbers/purchase": { "post": { "description": "Purchases the selected provider number and adds it to the authenticated workspace for routing.", "operationId": "purchasePhoneNumber", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasePhoneNumberRequest" }, "examples": { "request": { "summary": "Purchase a phone number", "value": { "phoneNumber": "+14155552671", "telephonyProviderId": "plivo_123456", "countryISO": "US" } } } } } }, "responses": { "200": { "description": "Phone number purchase initiated and record created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchasePhoneNumberResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "phoneNumber": "+1234567890", "status": "active", "message": "string", "organizationPhoneNumber": { "sip_trunk_enabled": false } } } } } } }, "201": { "description": "Phone number purchased and registered successfully.", "content": { "application/json": { "examples": { "success": { "summary": "Successful response", "value": { "phoneNumber": "+14155552671", "status": "active", "message": "Phone number purchased and registered successfully", "organizationPhoneNumber": { "id": "phn_abc123", "phone_number": "+14155552671", "provider": "plivo", "status": "active", "country_code": "US", "nickname": "US Sales Line" } } } } } } }, "400": { "description": "Invalid request or failed to purchase", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "country_iso is required", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Purchase Phone Number", "tags": [ "Phone Numbers" ] } }, "/v1/organization-phone-numbers/sip-trunks": { "post": { "operationId": "linkSipTrunk", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkSipTrunkRequest" }, "examples": { "request": { "summary": "Link a SIP trunk", "value": { "phoneNumber": "+14155552671", "terminationUri": "31974861099010243.zt.plivo.com:5060", "nickname": "US BYOC Line" } } } } } }, "responses": { "201": { "description": "SIP trunk linked successfully.", "content": { "application/json": { "examples": { "success": { "summary": "Successful response", "value": { "id": "phn_abc123", "phone_number": "+14155552671", "provider": "plivo", "status": "active", "country_code": "US", "nickname": "US BYOC Line" } } } } } }, "400": { "description": "Invalid input or missing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "country_iso is required", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "409": { "description": "Phone number already registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "409 Conflict", "value": { "statusCode": 409, "message": "Phone number already registered", "error": "Conflict" } } } } } }, "502": { "description": "SIP trunk registration failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "502 Bad Gateway", "value": { "statusCode": 502, "message": "SIP trunk registration failed", "error": "Bad Gateway" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Link SIP Trunk", "tags": [ "Phone Numbers" ], "description": "Registers a bring-your-own number with SIP trunk credentials for workspace routing." } }, "/v1/organization-phone-numbers/{id}": { "delete": { "description": "Deletes a workspace phone number, releases its provider rental or SIP connection, and prevents future DialNexa routing. The request is blocked if the number is the workspace default or is used by an active workflow.", "operationId": "deletePhoneNumber", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Phone number ID", "schema": { "example": "phn_abc123", "type": "string" } } ], "responses": { "200": { "description": "Phone number deleted successfully." }, "400": { "description": "Invalid phone number ID format." }, "401": { "description": "Unauthorized - missing or invalid API key." }, "403": { "description": "Forbidden - phone number does not belong to your organization." }, "404": { "description": "Phone number not found." }, "409": { "description": "Conflict - phone number is the organization default or has active workflows." }, "500": { "description": "Internal server error." } }, "security": [ { "bearer": [] } ], "summary": "Delete Phone Number", "tags": [ "Phone Numbers" ] }, "get": { "operationId": "getPhoneNumber", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Phone number ID", "schema": { "example": "phn_abc123", "type": "string" } } ], "responses": { "200": { "description": "Phone number returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "phn_abc123" }, "phone_number": { "type": "string", "example": "+919876543210" }, "provider": { "type": "string" }, "status": { "type": "string" } } }, "examples": { "success": { "summary": "Successful response", "value": { "id": "phn_abc123", "phone_number": "+14155552671", "provider": "plivo", "status": "active", "country_code": "US", "nickname": "US Sales Line" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - phone number does not belong to your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Phone number not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Phone number not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Phone Number Details", "tags": [ "Phone Numbers" ], "description": "Returns one workspace phone number and its routing configuration." } }, "/v1/transcribers": { "get": { "operationId": "listTranscribers", "parameters": [], "responses": { "200": { "description": "Transcribers returned successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Transcriber" } }, "examples": { "success": { "summary": "Successful response", "value": [ { "id": "trs_deepgram_nova_2", "name": "Deepgram Nova 2", "provider": "deepgram", "supports_fallback": true } ] } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Transcribers", "tags": [ "Transcribers" ], "description": "Returns the complete catalog of speech-to-text transcribers available for agents." } }, "/v1/transcribers/fallback": { "get": { "description": "Returns all transcribers eligible for use as a fallback STT provider. Use this list to populate the Fallback STT selector when configuring per-agent STT fallback settings.", "operationId": "listFallbackTranscribers", "parameters": [], "responses": { "200": { "description": "Fallback-eligible transcribers returned successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "trs_tr0deepnova3xx" }, "name": { "type": "string", "example": "Deepgram Nova 2" }, "provider": { "type": "string", "example": "deepgram" }, "model_id": { "type": "string", "example": "nova-2" }, "description": { "type": "string", "nullable": true }, "supported_language_codes": { "type": "array", "items": { "type": "string" }, "nullable": true, "example": null, "description": "null means all languages supported" } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key." }, "403": { "description": "Forbidden - API key does not have access to this organization." }, "500": { "description": "Internal server error." } }, "security": [ { "bearer": [] } ], "summary": "List Fallback Transcribers", "tags": [ "Transcribers" ] } }, "/v1/transcribers/{id}": { "get": { "operationId": "getTranscriber", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Transcriber ID", "schema": { "example": "trs_abc123", "type": "string" } } ], "responses": { "200": { "description": "Transcriber returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transcriber" }, "examples": { "success": { "summary": "Successful response", "value": { "id": "trs_deepgram_nova_2", "name": "Deepgram Nova 2", "provider": "deepgram", "supports_fallback": true } } } } } }, "400": { "description": "Invalid catalog ID format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid catalog ID format", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Transcriber not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Transcriber not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Transcriber Details", "tags": [ "Transcribers" ], "description": "Returns one speech-to-text transcriber catalog record by ID." } }, "/v1/user-webhooks": { "post": { "description": "Registers a new webhook URL for your organization. The secret is returned only once at creation - store it securely. For v1 call-ended deliveries, DialNexa sends a plain JSON body and an x-nexa-signature header in the format sha256= computed with HMAC-SHA256 over the raw request body.", "operationId": "createWebhook", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" }, "examples": { "request": { "summary": "Create a webhook", "value": { "url": "https://example.com/dialnexa/webhook", "events": [ "call.completed" ], "is_active": true, "secret": "replace-with-a-long-random-secret" } } } } } }, "responses": { "201": { "description": "Webhook created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Webhook created successfully" }, "webhook": { "type": "object", "properties": { "id": { "type": "string", "example": "webhook_abc123" }, "url": { "type": "string", "example": "https://webhook.site/your-endpoint" }, "events": { "type": "array", "items": { "type": "string" }, "example": [ "call.completed", "call.failed" ] }, "is_active": { "type": "boolean", "example": true }, "secret": { "type": "string", "example": "mySuperSecret", "description": "Shown once at creation only" }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "id": "webhook_abc123", "url": "https://example.com/dialnexa/webhook", "events": [ "call.completed" ], "is_active": true, "createdAt": "2026-07-03T10:30:00.000Z" } } } } } }, "400": { "description": "Bad request - missing required fields or invalid URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "url must be a valid URL", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Create Webhook", "tags": [ "Webhooks" ] }, "get": { "description": "Returns paginated webhook registrations. Secrets are masked in all list responses.", "operationId": "listWebhooks", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Results per page (default: 10)", "schema": { "example": 10, "type": "number" } }, { "name": "page", "required": false, "in": "query", "description": "Page number (default: 1)", "schema": { "example": 1, "type": "number" } } ], "responses": { "200": { "description": "Webhooks returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Webhooks fetched successfully" }, "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "webhook_abc123" }, "url": { "type": "string", "example": "https://webhook.site/your-endpoint" }, "events": { "type": "array", "items": { "type": "string" }, "example": [ "call.completed" ] }, "is_active": { "type": "boolean", "example": true }, "secret": { "type": "string", "example": "********", "description": "Always masked in list responses" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 10 }, "total": { "type": "number", "example": 5 }, "totalPages": { "type": "number", "example": 1 } } }, "examples": { "success": { "summary": "Successful response", "value": { "total": 1, "page": 1, "limit": 10, "webhooks": [ { "id": "webhook_abc123", "url": "https://example.com/dialnexa/webhook", "events": [ "call.completed" ], "is_active": true, "createdAt": "2026-07-03T10:30:00.000Z" } ] } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Webhooks", "tags": [ "Webhooks" ] } }, "/v1/user-webhooks/{id}": { "patch": { "description": "Update URL, events, or active status. Partial updates supported.", "operationId": "updateWebhook", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook ID", "schema": { "example": "webhook_abc123", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" }, "examples": { "request": { "summary": "Update a webhook", "value": { "is_active": false } } } } } }, "responses": { "200": { "description": "Webhook updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Webhook updated successfully" }, "webhook": { "type": "object", "properties": { "id": { "type": "string", "example": "webhook_abc123" }, "url": { "type": "string", "example": "https://webhook.site/new-endpoint" }, "events": { "type": "array", "items": { "type": "string" }, "example": [ "call.completed" ] }, "is_active": { "type": "boolean", "example": false } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "id": "webhook_abc123", "url": "https://example.com/dialnexa/webhook", "events": [ "call.completed" ], "is_active": false, "createdAt": "2026-07-03T10:30:00.000Z" } } } } } }, "400": { "description": "Bad request - invalid fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "url must be a valid URL", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Webhook not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Webhook not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Update Webhook", "tags": [ "Webhooks" ] }, "delete": { "description": "Deletes a webhook so new events stop being delivered.", "operationId": "deleteWebhook", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook ID", "schema": { "example": "webhook_abc123", "type": "string" } } ], "responses": { "200": { "description": "Webhook deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Webhook deleted successfully" }, "id": { "type": "string", "example": "webhook_abc123" } } }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Webhook deleted successfully" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Webhook not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Webhook not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete Webhook", "tags": [ "Webhooks" ] }, "get": { "operationId": "getWebhook", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Webhook ID", "schema": { "example": "webhook_abc123", "type": "string" } } ], "responses": { "200": { "description": "Webhook returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Webhook fetched successfully" }, "webhook": { "type": "object", "properties": { "id": { "type": "string", "example": "webhook_abc123" }, "url": { "type": "string", "example": "https://webhook.site/your-endpoint" }, "events": { "type": "array", "items": { "type": "string" }, "example": [ "call.completed" ] }, "is_active": { "type": "boolean", "example": true }, "secret": { "type": "string", "example": "********" }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "id": "webhook_abc123", "url": "https://example.com/dialnexa/webhook", "events": [ "call.completed" ], "is_active": true, "createdAt": "2026-07-03T10:30:00.000Z" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Webhook not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Webhook not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Webhook Details", "tags": [ "Webhooks" ], "description": "Returns one webhook registration; its signing secret is masked after creation." } }, "/v1/voices": { "get": { "description": "Returns all available voices with optional filtering by provider, accent, gender, or name.", "operationId": "listVoices", "parameters": [ { "name": "provider", "required": false, "in": "query", "description": "Filter by TTS provider", "schema": { "enum": [ "elevenlabs", "smallestai", "sarvam", "cartesia" ], "type": "string" } }, { "name": "accent", "required": false, "in": "query", "description": "Accent of the voice", "schema": { "enum": [ "indian", "british", "american", "canadian", "african", "australian", "swedish" ], "type": "string" } }, { "name": "gender", "required": false, "in": "query", "description": "Gender of the voice", "schema": { "enum": [ "male", "female", "non-binary" ], "type": "string" } }, { "name": "name", "required": false, "in": "query", "description": "Search by voice name", "schema": { "example": "English", "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "Page number (starts from 1)", "schema": { "default": "1", "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Max 50", "schema": { "default": "20", "example": 20, "type": "number" } }, { "name": "language_id", "required": false, "in": "query", "description": "Filter voices that support a specific language ID", "schema": { "example": "abc12345678901", "type": "string" } }, { "name": "llm_id", "required": false, "in": "query", "description": "Filter voices compatible with a specific LLM ID (S2S models only)", "schema": { "example": "abc12345678901", "type": "string" } } ], "responses": { "200": { "description": "Voices returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "voices": { "type": "array", "items": { "type": "object" } }, "total": { "type": "number" }, "page": { "type": "number" }, "limit": { "type": "number" }, "totalPages": { "type": "number" } } }, "examples": { "success": { "summary": "Successful response", "value": { "voices": [ { "id": "voice_abc123", "name": "Aditi", "provider": "elevenlabs", "language_code": "en-IN", "gender": "female" } ], "total": 1, "page": 1, "limit": 20, "totalPages": 1 } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Voices", "tags": [ "Voices" ] } }, "/v1/voices/accents": { "get": { "description": "Returns the distinct accent values across all available voices, optionally filtered by provider.", "operationId": "listVoiceAccents", "parameters": [ { "name": "provider", "required": false, "in": "query", "schema": { "enum": [ "elevenlabs", "smallestai", "sarvam", "cartesia" ], "type": "string" } } ], "responses": { "200": { "description": "Voice accents returned successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "example": "indian" } }, "examples": { "success": { "summary": "Successful response", "value": [ "indian", "american", "british" ] } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Voice Accents", "tags": [ "Voices" ] } }, "/v1/voices/s2s": { "get": { "description": "Returns voices that support speech-to-speech mode, along with their compatible languages and LLMs.", "operationId": "listSpeechToSpeechVoices", "parameters": [], "responses": { "200": { "description": "Speech to speech voices returned successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeechToSpeechVoicesResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "voices": [ { "id": "voice_s2s_abc123", "name": "Realtime Voice", "provider": "openai", "type": "speech_to_speech", "provider_voice_id": "ash", "gender": "neutral", "accent": null, "icon": null, "recording": null, "languages": [], "llms": [] } ] } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Speech To Speech Voices", "tags": [ "Voices" ] } }, "/v1/voices/{id}": { "get": { "operationId": "getVoice", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Voice ID", "schema": { "example": "voice_abc123", "type": "string" } } ], "responses": { "200": { "description": "Voice returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "voice_abc123" }, "name": { "type": "string" }, "provider": { "type": "string" }, "gender": { "type": "string" }, "accent": { "type": "string" } } }, "examples": { "success": { "summary": "Successful response", "value": { "id": "voice_abc123", "name": "Aditi", "provider": "elevenlabs", "language_code": "en-IN", "gender": "female", "preview_url": "https://example.com/preview.mp3" } } } } } }, "400": { "description": "Invalid catalog ID format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid catalog ID format", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Voice not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Voice not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Voice Details", "tags": [ "Voices" ], "description": "Returns one voice catalog record by ID." } }, "/v1/voices/{id}/languages": { "get": { "operationId": "listVoiceLanguages", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Voice ID", "schema": { "example": "voice_abc123", "type": "string" } } ], "responses": { "200": { "description": "Voice languages returned successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "lang_abc123" }, "code": { "type": "string", "example": "en" }, "name": { "type": "string", "example": "English" } } } }, "examples": { "success": { "summary": "Successful response", "value": [ { "id": "lang_en_in", "name": "English (India)", "code": "en-IN" } ] } } } } }, "400": { "description": "Invalid catalog ID format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid catalog ID format", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - API key does not have access to this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Voice not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Voice not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Voice Language Details", "tags": [ "Voices" ], "description": "Returns the languages supported by one voice." } }, "/v1/workflows": { "get": { "operationId": "listWorkflows", "parameters": [ { "name": "sortOrder", "required": false, "in": "query", "schema": { "enum": [ "ASC", "DESC" ], "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "schema": { "example": "createdAt", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 20, "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } } ], "responses": { "200": { "description": "Workflows fetched successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 200 }, "message": { "type": "string", "example": "Workflows fetched successfully" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "workflow_abc123" }, "title": { "type": "string", "example": "Q3 Outreach Workflow" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "completed", "cancelled" ], "example": "active" }, "description": { "type": "string", "nullable": true, "example": "Automated follow-up sequence" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } }, "meta": { "type": "object", "properties": { "totalItems": { "type": "number", "example": 50 }, "itemsPerPage": { "type": "number", "example": 20 }, "totalPages": { "type": "number", "example": 3 }, "currentPage": { "type": "number", "example": 1 } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "statusCode": 200, "message": "Workflows fetched successfully", "data": [ { "id": "workflow_abc123", "title": "Q3 Outreach Workflow", "status": "active", "description": "Automated follow-up sequence", "createdAt": "2026-07-03T10:30:00.000Z", "updatedAt": "2026-07-03T10:45:00.000Z" } ], "meta": { "totalItems": 1, "itemsPerPage": 20, "totalPages": 1, "currentPage": 1 } } } } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Workflow validation failed", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Workflows", "tags": [ "Workflows" ], "description": "Returns workflows for the authenticated workspace in a data and meta pagination envelope." } }, "/v1/workflows/{id}": { "get": { "operationId": "getWorkflow", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Workflow ID", "schema": { "example": "workflow_abc123", "type": "string" } } ], "responses": { "200": { "description": "Workflow fetched successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 200 }, "message": { "type": "string", "example": "Workflow fetched successfully" }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "workflow_abc123" }, "title": { "type": "string", "example": "Q3 Outreach Workflow" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "completed", "cancelled" ], "example": "active" }, "description": { "type": "string", "nullable": true, "example": "Automated follow-up sequence" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "examples": { "success": { "summary": "Successful response", "value": { "statusCode": 200, "message": "Workflow fetched successfully", "data": { "id": "workflow_abc123", "title": "Q3 Outreach Workflow", "status": "active", "description": "Automated follow-up sequence", "createdAt": "2026-07-03T10:30:00.000Z", "updatedAt": "2026-07-03T10:45:00.000Z" } } } } } } }, "400": { "description": "Invalid workflow ID format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Workflow validation failed", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "404": { "description": "Workflow not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Workflow not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Workflow Details", "tags": [ "Workflows" ], "description": "Returns one workflow and its current lifecycle state." } }, "/v1/workflows/{id}/status": { "patch": { "operationId": "updateWorkflowStatus", "summary": "Update Workflow Status", "description": "Changes a workflow status. Use `activate` to start execution for all leads, `deactivate` to pause a currently active workflow, `pause` to pause a running workflow, or `resume` to continue a paused workflow.", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Workflow ID", "schema": { "example": "workflow_abc123", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "activate", "deactivate", "pause", "resume" ], "example": "activate", "description": "The workflow status transition to apply." } } }, "examples": { "activate": { "summary": "Activate a workflow", "value": { "action": "activate" } }, "deactivate": { "summary": "Deactivate a workflow", "value": { "action": "deactivate" } }, "pause": { "summary": "Pause a workflow", "value": { "action": "pause" } }, "resume": { "summary": "Resume a workflow", "value": { "action": "resume" } } } } } }, "responses": { "200": { "description": "Workflow status updated successfully.", "content": { "application/json": { "examples": { "success": { "summary": "Successful response", "value": { "statusCode": 200, "message": "Workflow activated successfully", "data": { "id": "workflow_abc123", "title": "Q3 Outreach Workflow", "status": "active", "description": "Automated follow-up sequence", "createdAt": "2026-07-03T10:30:00.000Z", "updatedAt": "2026-07-03T10:45:00.000Z" } } } }, "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 200 }, "message": { "type": "string", "example": "Workflow activated successfully" }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "workflow_abc123" }, "title": { "type": "string", "example": "Q3 Outreach Workflow" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "completed", "cancelled" ], "example": "active" }, "description": { "type": "string", "nullable": true, "example": "Automated follow-up sequence" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid action, invalid workflow status, or workflow validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "Invalid action. Must be one of: activate, deactivate, pause, resume", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - workflow does not belong to your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this resource", "error": "Forbidden" } } } } } }, "404": { "description": "Workflow not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Workflow not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "tags": [ "Workflows" ] } }, "/v1/workflows/{workflowId}/leads": { "post": { "operationId": "uploadWorkflowLeads", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "description": "Workflow ID", "schema": { "example": "workflow_abc123", "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "CSV or Excel file with leads data" } } }, "examples": { "request": { "summary": "Upload workflow leads file", "value": { "file": "workflow-leads.csv" } } } } } }, "responses": { "201": { "description": "File processed successfully.", "content": { "application/json": { "examples": { "success": { "summary": "Successful response", "value": { "statusCode": 201, "message": "Leads uploaded successfully", "data": { "+919876543210": [ "lead_abc123" ] }, "count": 1 } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "400 Bad Request", "value": { "statusCode": 400, "message": "File must be a CSV or Excel file (.csv, .xlsx, .xls)", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - workflow does not belong to your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this workflow", "error": "Forbidden" } } } } } }, "404": { "description": "Workflow not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Workflow not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Upload Workflow Leads", "tags": [ "Workflow Leads" ], "description": "Uploads and enrolls leads in one workflow from a supported file." }, "get": { "operationId": "listWorkflowLeads", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "description": "Workflow ID", "schema": { "example": "workflow_abc123", "type": "string" } }, { "name": "leadIds", "required": false, "in": "query", "description": "Comma-separated lead IDs to filter", "schema": { "example": "id1,id2", "type": "string" } } ], "responses": { "200": { "description": "Leads returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 200 }, "message": { "type": "string", "example": "Leads fetched successfully" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "lead_abc123" }, "phone_number": { "type": "string", "example": "+919876543210" }, "dynamic_variables": { "type": "object", "example": { "name": "John", "company": "Acme" } }, "status": { "type": "string", "example": "pending" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "count": { "type": "number", "example": 42 } } }, "examples": { "success": { "summary": "Successful response", "value": { "statusCode": 200, "message": "Leads fetched successfully", "data": [ { "id": "lead_abc123", "phone_number": "+919876543210", "dynamic_variables": { "customer_name": "Priya Sharma", "loan_amount": "500000" }, "status": "pending", "createdAt": "2026-07-03T10:30:00.000Z" } ], "count": 1 } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - workflow does not belong to your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this workflow", "error": "Forbidden" } } } } } }, "404": { "description": "Workflow not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Workflow not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "List Workflow Leads", "tags": [ "Workflow Leads" ], "description": "Returns leads enrolled in one workflow." } }, "/v1/workflows/{workflowId}/leads/variable-keys": { "get": { "operationId": "listWorkflowLeadVariableKeys", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "description": "Workflow ID", "schema": { "example": "workflow_abc123", "type": "string" } } ], "responses": { "200": { "description": "Variable keys returned successfully.", "content": { "application/json": { "examples": { "success": { "summary": "Successful response", "value": { "statusCode": 200, "message": "Variable keys fetched successfully", "data": { "keys": [ "customer_name", "loan_amount", "product" ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - workflow does not belong to your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this workflow", "error": "Forbidden" } } } } } }, "404": { "description": "Workflow not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Workflow not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Workflow Lead Variables", "tags": [ "Workflow Leads" ], "description": "Returns dynamic variable keys discovered across leads in one workflow." } }, "/v1/workflows/{workflowId}/leads/{id}": { "delete": { "operationId": "deleteWorkflowLead", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "description": "Workflow ID", "schema": { "example": "workflow_abc123", "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "Lead ID", "schema": { "example": "lead_abc123", "type": "string" } } ], "responses": { "200": { "description": "Lead removed successfully.", "content": { "application/json": { "examples": { "success": { "summary": "Successful response", "value": { "statusCode": 200, "message": "Lead removed successfully" } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - workflow does not belong to your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this workflow", "error": "Forbidden" } } } } } }, "404": { "description": "Lead not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Workflow lead not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete Workflow Lead", "tags": [ "Workflow Leads" ], "description": "Removes one lead from a workflow and prevents it from advancing to later steps." } }, "/v1/workflows/{workflowId}/leads/{id}/history": { "get": { "operationId": "getWorkflowLeadHistory", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "description": "Workflow ID", "schema": { "example": "workflow_abc123", "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "Lead ID", "schema": { "example": "lead_abc123", "type": "string" } } ], "responses": { "200": { "description": "Lead execution history returned successfully.", "content": { "application/json": { "examples": { "success": { "summary": "Successful response", "value": { "statusCode": 200, "message": "Lead history fetched successfully", "data": { "lead": { "id": "lead_abc123", "phone_number": "+919876543210", "dynamic_variables": { "customer_name": "Priya Sharma", "loan_amount": "500000" }, "status": "pending", "createdAt": "2026-07-03T10:30:00.000Z" }, "history": [ { "node_id": "node_start", "node_type": "VOICE_CALL", "label": "Initial call", "status": "completed", "call_id": "call_abc123", "started_at": "2026-07-03T10:30:00.000Z", "ended_at": "2026-07-03T10:32:00.000Z" } ] } } } } } } }, "401": { "description": "Unauthorized - missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "401 Unauthorized", "value": { "statusCode": 401, "message": "API key is missing or invalid", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - workflow does not belong to your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "403 Forbidden", "value": { "statusCode": 403, "message": "You do not have permission to access this workflow", "error": "Forbidden" } } } } } }, "404": { "description": "Lead not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "404 Not Found", "value": { "statusCode": 404, "message": "Workflow lead not found", "error": "Not Found" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "500 Internal Server Error", "value": { "statusCode": 500, "message": "Internal server error", "error": "Internal Server Error" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Get Lead Execution History", "tags": [ "Workflow Leads" ], "description": "Returns node-by-node execution history for one workflow lead." } } }, "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "type": "http" } }, "schemas": { "Agents": { "type": "object", "properties": { "id": { "type": "string", "example": "agent_2g7Xy3tY53gRlp", "description": "Signed agent ID" }, "folder_id": { "type": "string", "nullable": true }, "current_version_number": { "type": "integer", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "agent_type": { "type": "string", "enum": [ "Single_Prompt_Agent", "Conversational_Flow_Agent" ] }, "pipeline_type": { "type": "string", "enum": [ "Cascaded", "Speech_To_Speech" ], "nullable": true }, "webhook_id": { "type": "string", "nullable": true }, "current_version": { "type": "object", "properties": { "agent_id": { "type": "string" }, "version_number": { "type": "integer" }, "version_title": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "is_published": { "type": "boolean" }, "language_id": { "type": "string", "nullable": true }, "voice_id": { "type": "string", "nullable": true }, "llm_id": { "type": "string", "nullable": true }, "transcriber_id": { "type": "string", "nullable": true }, "fallback_stt_enabled": { "type": "boolean" }, "stt_fallback_transcriber_id": { "type": "string", "nullable": true }, "post_call_analysis_llm_id": { "type": "string", "nullable": true } }, "nullable": true }, "versions": { "type": "array", "items": { "type": "object", "properties": { "agent_id": { "type": "string" }, "version_number": { "type": "integer" }, "version_title": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "is_published": { "type": "boolean" }, "language_id": { "type": "string", "nullable": true }, "voice_id": { "type": "string", "nullable": true }, "llm_id": { "type": "string", "nullable": true }, "transcriber_id": { "type": "string", "nullable": true }, "fallback_stt_enabled": { "type": "boolean" }, "stt_fallback_transcriber_id": { "type": "string", "nullable": true }, "post_call_analysis_llm_id": { "type": "string", "nullable": true } } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "agent_type" ] }, "CallLogs": { "type": "object", "properties": { "id": { "type": "string", "example": "call_abc123", "description": "Signed call ID" } }, "required": [ "id" ] }, "ErrorResponse": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 400 }, "message": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "phone_number must be a valid E.164 phone number" }, "error": { "type": "string", "example": "Bad Request" } }, "required": [ "statusCode", "message", "error" ] }, "KnowledgeBase": { "type": "object", "properties": { "id": { "type": "string", "example": "kb_abc123", "description": "Signed knowledge base ID." }, "name": { "type": "string", "example": "Loan FAQ", "maxLength": 150 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name" ] }, "Languages": { "type": "object", "properties": { "id": { "type": "string", "example": "lang_abc123", "description": "Signed language ID" } }, "required": [ "id" ] }, "Llm": { "type": "object", "properties": { "id": { "type": "string", "example": "llm_abc123", "description": "Signed LLM ID" } }, "required": [ "id" ] }, "OrganizationPhoneNumber": { "type": "object", "properties": { "sip_trunk_enabled": { "type": "boolean", "description": "When true, Speech IO uses SIP trunking (e.g. asterisk) for this number.", "default": false } }, "required": [ "sip_trunk_enabled" ] }, "Transcriber": { "type": "object", "properties": { "id": { "type": "string", "example": "trs_abc123", "description": "Signed transcriber ID" } }, "required": [ "id" ] }, "CreateAgentRequest": { "type": "object", "properties": { "voicemail_detection": { "type": "boolean", "description": "Indicates whether voicemail detection is enabled", "default": true, "example": true }, "hangup_on_voicemail": { "type": "boolean", "description": "Hang up immediately when voicemail is detected instead of leaving a message", "default": false, "example": false }, "voicemail_message": { "type": "string", "description": "Message spoken when voicemail is detected and hangup_on_voicemail is false. Supports Handlebars template syntax such as {{variable}} and must be valid Handlebars template text.", "example": "Hi, please call us back at your convenience.", "default": "Please leave a message after the beep." }, "listen_for_keypad": { "type": "boolean", "description": "Whether the agent listens for keypad (DTMF) input from the caller", "example": true, "default": true }, "keypad_timeout_sec": { "type": "number", "description": "Seconds to wait for keypad input before timing out (0-15)", "example": 5, "default": 5, "minimum": 0, "maximum": 15 }, "termination_key": { "type": "string", "description": "Single character key that ends the call (digits, * or #)", "example": "#", "default": "#" }, "digit_limit": { "type": "number", "description": "Maximum number of DTMF digits to collect from the caller (1-50)", "example": 1, "default": 1, "minimum": 1, "maximum": 50 }, "end_call_on_silence_sec": { "type": "number", "description": "Seconds of silence after which the call is automatically ended. Accepted range: 15 to 30 seconds. Must be more than 5 seconds above reminder_message_interval when reminders are configured.", "example": 20, "default": 15, "minimum": 15, "maximum": 30 }, "max_call_duration_sec": { "type": "number", "description": "Maximum call duration in seconds before the call is forcibly ended. Accepted range: 60 to 5400 seconds for cascaded agents. Speech to Speech agents are capped at 3600 seconds.", "example": 600, "default": 600, "minimum": 60, "maximum": 5400 }, "pause_before_speaking_sec": { "type": "number", "description": "Seconds of silence inserted before the agent starts speaking", "example": 0, "default": 2, "minimum": 0 }, "ring_duration_sec": { "type": "number", "description": "How long to let the phone ring before treating the call as unanswered (seconds)", "example": 30, "default": 5, "minimum": 1 }, "background_sound": { "type": "string", "description": "Background sound file or identifier" }, "background_sound_volume": { "type": "number", "minimum": 0, "maximum": 2, "default": 1, "description": "Volume of background sound (0 to 2)" }, "ambient_noise": { "type": "boolean", "description": "Enable or disable ambient noise playback on the call" }, "responsiveness": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5, "description": "Responsiveness level from 0 to 1." }, "interruption_sensitivity": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5, "description": "Interruption sensitivity level (0 to 1)" }, "response_eagerness": { "type": "number", "minimum": 0, "maximum": 1, "default": 1, "description": "How eagerly the agent responds (0 to 1). Only applied when transcriber is Soniox." }, "backchanneling": { "type": "boolean", "default": false, "description": "Enable or disable backchanneling" }, "backchannel_frequency": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5, "description": "Backchannel frequency from (0 to 1)" }, "transcription_mode": { "type": "string", "enum": [ "optimize_for_speed", "optimize_for_accuracy" ], "default": "optimize_for_speed", "description": "Mode for transcription" }, "denoising_mode": { "type": "string", "enum": [ "remove_noise", "remove_noise_and_speech" ], "description": "Mode for denoising audio input" }, "speech_normalization": { "type": "boolean", "default": false, "description": "Enable or disable speech normalization" }, "transcript_formatting": { "type": "boolean", "default": false, "description": "Enable or disable transcript formatting" }, "backchannel_keywords": { "type": "string", "description": "Comma-separated list of backchannel keywords" }, "boosted_keywords": { "type": "string", "description": "Comma-separated recognition hints for supported Deepgram and Soniox transcribers. Terms can contain letters, numbers, and spaces only. The normalized list supports up to 100 terms, 50 characters per term, and 2000 total characters.", "maxLength": 2000, "example": "DialNexa, Nexa Prime, customer success" }, "reminder_message_interval": { "type": "number", "default": 9, "description": "Interval between reminder messages (in seconds)" }, "reminder_message_frequency": { "type": "number", "default": 1, "description": "Frequency of reminder messages" }, "transcriber_id": { "type": "string", "nullable": true, "description": "ID of the transcriber catalog entry" }, "fallback_stt_enabled": { "type": "boolean", "default": false, "description": "Enable parallel fallback STT for this agent" }, "stt_fallback_transcriber_id": { "type": "string", "nullable": true, "description": "Fallback STT transcriber catalog entry" }, "stt_fallback_wait_ms": { "type": "number", "minimum": 0, "description": "Milliseconds to wait for primary STT after fallback finalizes first" }, "audio_cache_enabled": { "type": "boolean", "description": "Enable TTS audio caching for this agent" }, "folder_id": { "type": "string", "description": "ID of the folder this agent belongs to", "example": "fld_abc123xyz789" }, "agent_type": { "type": "string", "description": "Type of the agent", "enum": [ "Single_Prompt_Agent", "Conversational_Flow_Agent" ], "example": "Single_Prompt_Agent", "default": "Single_Prompt_Agent" }, "pipeline_type": { "type": "string", "description": "Pipeline subtype for Single_Prompt_Agent. Cascaded = ASR→LLM→TTS pipeline. Speech_To_Speech = direct speech model. Null for Conversational_Flow_Agent.", "enum": [ "Cascaded", "Speech_To_Speech" ], "example": "Cascaded", "default": "Cascaded" }, "title": { "type": "string", "description": "Title of the agent (max 70 characters)", "example": "Customer Support Agent", "maxLength": 70 }, "version_title": { "type": "string", "description": "Version title (optional, will be auto-generated if not provided, max 35 characters)", "example": null, "nullable": true, "maxLength": 35 }, "description": { "type": "string", "description": "Description of the agent", "example": "This agent handles customer support inquiries" }, "timezone": { "type": "string", "description": "Timezone for the agent", "example": "Asia/Kolkata" }, "outbound_phone_number_id": { "type": "string", "description": "ID of the outbound phone number to use for this agent. Must be an existing phone number ID in your organization. Stored on the draft at creation; live outbound routing is claimed when the version is published." }, "inbound_phone_number_id": { "type": "string", "description": "ID of the inbound phone number to use for this agent. Must be an existing phone number ID in your organization. Stored on the draft at creation; live inbound routing is claimed when the version is published." }, "llm_id": { "type": "string", "description": "ID of the LLM associated with the agent", "example": "A1B2C3D4E5F6G7" }, "language_id": { "type": "string", "description": "ID of the language the agent speaks", "example": "1" }, "voice_id": { "type": "string", "description": "ID of the voice used by the agent", "example": "VOICE123456789" }, "webhook_id": { "type": "string", "description": "ID of the webhook associated with the agent", "example": "wh_12345678901234" }, "prompt_text": { "type": "string", "description": "Main instructions for the agent. Supports Handlebars template syntax such as {{variable}} for dynamic content. Must be valid Handlebars template text.", "example": "Hello, how can I assist you today?" }, "system_prompt_text": { "type": "string", "description": "Static system instructions for the agent. Use prompt_text for dynamic content via {{variable}} syntax.", "example": "You are a helpful customer support agent named Sarah." }, "node_positions": { "type": "string", "description": "Node positions for Conversational_Flow_Agent type (stored as JSON string)", "example": "{\"node1\": {\"x\": 100, \"y\": 200}}" }, "conversation_start_type": { "type": "string", "description": "Who starts the conversation", "example": "user", "enum": [ "user", "agent_dynamic", "agent_defined" ] }, "welcome_message": { "type": "string", "description": "Opening message spoken by the agent at the start of the call. Supports Handlebars template syntax such as {{variable}} and must be valid Handlebars template text.", "example": "Welcome to our service!" }, "allow_interruptions": { "type": "boolean", "description": "Whether the agent allows interruptions", "example": true }, "json_output_instructions": { "type": "object", "description": "Instructions for JSON output", "example": { "format": "detailed" } }, "knowledge_base_ids": { "description": "IDs of the knowledge bases attached to this agent version", "example": [ "kb_abc123", "kb_def456" ], "type": "array", "items": { "type": "string" } }, "kb_max_chunks": { "type": "number", "description": "Maximum number of RAG chunks to fetch (1-10)", "example": 5, "minimum": 1, "maximum": 10 }, "kb_min_score": { "type": "number", "description": "Minimum similarity score threshold for RAG results (0-1)", "example": 0.5, "minimum": 0, "maximum": 1 }, "default_dynamic_variables": { "type": "object", "description": "Default values for dynamic variables used in Handlebars templates. For call-transfer flows, agent_transfer_destinations accepts up to 7 pipe-separated phone numbers. Each number must use US +1 or India +91 and exactly 10 digits after the country code.", "example": { "firstName": "John", "lastName": "Doe", "courseType": "Math" } }, "voice_model_id": { "type": "string", "description": "Speech synthesis model for the selected voice. The model must belong to the same provider as voice_id. Omit this field when you want DialNexa to apply the recommended model. For ElevenLabs voices, use eleven_flash_v2_5 where supported. To find supported models for one voice, call GET /v1/voices/{voice_id}/voice-models.", "example": "voice_model_abc123" }, "voice_speed": { "type": "number", "description": "Voice speed (0.25 to 4.0)", "example": 1, "minimum": 0.25, "maximum": 4 }, "voice_temperature": { "type": "number", "description": "Voice temperature (0.0 to 2.0)", "example": 1, "minimum": 0, "maximum": 2 }, "voice_volume": { "type": "number", "description": "Voice volume (0 to 10)", "example": 1, "minimum": 0, "maximum": 10 }, "voice_pitch": { "type": "number", "description": "Pitch adjustment of the voice (-1 to 1)", "example": 0, "minimum": -1, "maximum": 1 }, "llm_temperature": { "type": "number", "description": "LLM temperature (0.0 to 2.0)", "example": 0.1, "minimum": 0, "maximum": 2 }, "opt_out_sensitive_data_storage": { "type": "boolean", "description": "Opt out of sensitive data storage", "example": false }, "opt_in_secure_urls": { "type": "boolean", "description": "Opt in to secure URLs", "example": false }, "fallback_llm_enabled": { "type": "boolean", "description": "Enable fallback LLM for this agent", "example": false }, "predictive_preprocessing_enabled": { "type": "boolean", "description": "Enable predictive preprocessing for this agent version", "example": false }, "llm_fallback_delay_ms": { "type": "number", "description": "Milliseconds to wait before triggering the fallback LLM", "example": 500, "nullable": true }, "llm_fallback_model": { "type": "string", "description": "ID (llms.id) of the LLM to use as fallback", "example": "abc123xyz789ab", "nullable": true }, "fallback_voices": { "type": "array", "description": "Fallback voices for TTS. Used when the primary voice is unavailable.", "items": { "type": "object", "properties": { "voice_id": { "type": "string", "example": "VOICE123456789" }, "voice_name": { "type": "string", "example": "Fallback Voice" }, "provider_voice_id": { "type": "string", "example": "en-US-JennyNeural" }, "provider": { "type": "string", "example": "azure" } } } }, "agent_functions": { "type": "array", "description": "Functions the agent can invoke during a call (e.g. end call, transfer, booking). Passed at create time; use PATCH to replace later.", "items": { "type": "object", "required": [ "displayName", "type", "description" ], "properties": { "displayName": { "type": "string", "example": "Book Calendar" }, "type": { "type": "string", "enum": [ "end_call", "call_transfer", "custom", "check_calendar_availability", "book_calendar", "integration" ], "example": "book_calendar" }, "description": { "type": "string", "example": "Books a calendar appointment for the caller" }, "config": { "type": "object", "example": { "api_key": "xxx", "calendar_id": "primary" } } } } }, "post_call_analysis": { "type": "array", "description": "Fields to extract from the call transcript after the call ends.", "items": { "type": "object", "required": [ "field_name", "field_type", "field_description" ], "properties": { "field_name": { "type": "string", "example": "customer_satisfaction" }, "field_type": { "type": "string", "enum": [ "NUMBER", "STRING", "BOOLEAN", "ENUM" ], "example": "NUMBER" }, "field_description": { "type": "string", "example": "Customer satisfaction rating from 1 to 5" } } } }, "postcall_analysis": { "type": "array", "description": "Alias for post_call_analysis (backward compatibility).", "items": { "type": "object", "properties": { "field_name": { "type": "string", "example": "customer_satisfaction" }, "field_type": { "type": "string", "enum": [ "NUMBER", "STRING", "BOOLEAN", "ENUM" ], "example": "NUMBER" }, "field_description": { "type": "string", "example": "Customer satisfaction rating from 1 to 5" } } } }, "agent_identity": { "type": "string", "description": "Agent identity (required for Conversational_Flow_Agent type on update)", "example": "You are a helpful customer support agent named Sarah." }, "agent_background": { "type": "string", "description": "Agent background (required for Conversational_Flow_Agent type on update)", "example": "You have 5 years of experience in customer support and specialize in helping customers with technical issues." }, "prompt_caching_enabled": { "type": "boolean", "description": "Enable OpenAI Prompt Caching for this agent version. DialNexa must enable this feature for your workspace.", "example": false } }, "required": [ "title", "language_id", "voice_id", "prompt_text" ] }, "CreateCallRequest": { "type": "object", "properties": { "phone_number": { "type": "string", "example": "+911234567890", "description": "Phone number to call (must include country code). Format: +[country code][phone number]" }, "agent_id": { "type": "string", "example": "mgao6051Rk718Y", "description": "Agent ID to use for the call. Must belong to the authenticated organization." }, "agent_version_number": { "type": "number", "example": 2, "description": "Specific agent version number to use (optional). If provided, must be a published version. If not provided, will use the latest published version." }, "metadata": { "type": "object", "example": { "customer_name": "John Doe", "customer_email": "john@example.com", "priority": "high" }, "description": "Metadata for the call including customer information and any additional context. This data will be available during the call for personalization." }, "notes": { "type": "object", "example": { "customer_name": "John Doe", "follow_up_required": true, "source": "crm" }, "description": "Optional notes stored on the call log. Must be a JSON object with at most 15 top-level keys." } }, "required": [ "phone_number", "agent_id", "metadata" ] }, "CreateCallResponse": { "type": "object", "properties": { "id": { "type": "string", "example": "call_mfgsn90vwcozgb", "description": "Unique call ID for tracking. Use this ID to reference the call in other API endpoints." }, "to_phone_number": { "type": "string", "example": "+911234567890", "description": "The phone number that will receive the call." }, "agent_id": { "type": "string", "example": "agent_mfgsn90vwcozgb", "description": "The ID of the agent used for this call." }, "agent_version_number": { "type": "number", "example": 2, "description": "The version number of the agent used for this call." } }, "required": [ "id", "to_phone_number", "agent_id" ] }, "CreateKnowledgeBaseRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the knowledge base (must be unique within the workspace)", "example": "Product Documentation", "maxLength": 150 } }, "required": [ "name" ] }, "CreateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "example": "https://webhook.site/your-endpoint", "description": "The URL to which webhook events will be sent." }, "events": { "example": [ "order.paid", "order.failed" ], "description": "List of events this webhook is subscribed to.", "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean", "example": true, "description": "Whether the webhook is active." }, "secret": { "type": "string", "example": "mySuperSecret", "description": "Secret used to sign webhook payloads." } }, "required": [ "url", "events", "secret" ] }, "LinkSipTrunkRequest": { "type": "object", "properties": { "phoneNumber": { "type": "string", "example": "+14155552671", "description": "E.164 phone number" }, "terminationUri": { "type": "string", "example": "31974861099010243.zt.plivo.com:5060", "description": "SIP termination host[:port]; must not use a sip: URI prefix" }, "sipTrunkUserName": { "type": "string", "description": "SIP authentication username" }, "sipTrunkPassword": { "type": "string", "description": "SIP authentication password." }, "nickname": { "type": "string", "description": "Display nickname for this trunk" } }, "required": [ "phoneNumber", "terminationUri" ] }, "AvailablePhoneNumber": { "type": "object", "properties": { "number": { "type": "string", "description": "The phone number" }, "type": { "type": "string", "description": "The type of phone number (local, tollfree, etc.)" }, "monthly_rental_rate": { "type": "string", "description": "The monthly rental rate for the phone number" }, "setup_rate": { "type": "string", "description": "The setup fee for the phone number" }, "voice_enabled": { "type": "boolean", "description": "Voice capability of the phone number" }, "sms_enabled": { "type": "boolean", "description": "SMS capability of the phone number" }, "mms_enabled": { "type": "boolean", "description": "MMS capability of the phone number" }, "country_iso": { "type": "string", "description": "Country ISO code" }, "number_format": { "type": "string", "description": "The number in international format" } }, "required": [ "number", "type", "monthly_rental_rate", "setup_rate", "voice_enabled", "sms_enabled", "mms_enabled", "country_iso", "number_format" ] }, "AvailablePhoneNumbersResponse": { "type": "object", "properties": { "api_id": { "type": "string", "description": "API ID for the request" }, "objects": { "description": "List of available phone numbers", "type": "array", "items": { "$ref": "#/components/schemas/AvailablePhoneNumber" } }, "meta": { "type": "object", "description": "Total count of available numbers" } }, "required": [ "api_id", "objects", "meta" ] }, "PurchasePhoneNumberRequest": { "type": "object", "properties": { "phoneNumber": { "type": "string", "example": "+1234567890", "description": "Phone number to purchase" }, "telephonyProviderId": { "type": "string", "example": "plivo_123456", "description": "ID of telephony provider (14-char string)" }, "countryISO": { "type": "string", "example": "US", "description": "Country ISO code (e.g., US, IN)" } }, "required": [ "phoneNumber", "telephonyProviderId", "countryISO" ] }, "PurchasePhoneNumberResponse": { "type": "object", "properties": { "phoneNumber": { "type": "string", "example": "+1234567890", "description": "Phone number" }, "status": { "type": "string", "enum": [ "active", "pending" ], "description": "Status of the phone number" }, "message": { "type": "string", "description": "Status message" }, "organizationPhoneNumber": { "description": "Organization phone number record", "allOf": [ { "$ref": "#/components/schemas/OrganizationPhoneNumber" } ] } }, "required": [ "phoneNumber", "status" ] }, "SpeechToSpeechLanguage": { "type": "object", "properties": { "id": { "type": "string", "example": "mj17k2hwviopty" }, "name": { "type": "string", "example": "Hindi" }, "code": { "type": "string", "example": "hi" } }, "required": [ "id", "name", "code" ] }, "SpeechToSpeechModel": { "type": "object", "properties": { "id": { "type": "string", "example": "llm_abc123456789" }, "name": { "type": "string", "example": "GPT Realtime 2" }, "provider": { "type": "string", "example": "openai" }, "provider_id": { "type": "string", "example": "gpt-realtime-2" } }, "required": [ "id", "name", "provider", "provider_id" ] }, "SpeechToSpeechVoice": { "type": "object", "properties": { "id": { "type": "string", "example": "voice_abc123456789" }, "name": { "type": "string", "example": "Ash" }, "provider": { "type": "string", "example": "openai", "nullable": true }, "provider_voice_id": { "type": "string", "example": "ash", "nullable": true }, "gender": { "type": "string", "example": "male" }, "accent": { "type": "string", "example": "american", "nullable": true }, "icon": { "type": "string", "nullable": true }, "recording": { "type": "string", "nullable": true }, "languages": { "type": "array", "items": { "$ref": "#/components/schemas/SpeechToSpeechLanguage" } }, "llms": { "type": "array", "items": { "$ref": "#/components/schemas/SpeechToSpeechModel" } } }, "required": [ "id", "name", "provider", "provider_voice_id", "gender", "accent", "icon", "recording", "languages", "llms" ] }, "SpeechToSpeechVoicesResponse": { "type": "object", "properties": { "voices": { "type": "array", "items": { "$ref": "#/components/schemas/SpeechToSpeechVoice" } } }, "required": [ "voices" ] }, "UpdateAgentRequest": { "type": "object", "properties": { "background_sound": { "type": "string", "description": "Background sound file or identifier" }, "background_sound_volume": { "type": "number", "minimum": 0, "maximum": 2, "description": "Volume of background sound (0 to 2)" }, "ambient_noise": { "type": "boolean", "description": "Enable or disable ambient noise playback on the call" }, "responsiveness": { "type": "number", "minimum": 0, "maximum": 5, "description": "Responsiveness level from 0 to 1." }, "interruption_sensitivity": { "type": "number", "minimum": 0, "maximum": 1, "description": "Interruption sensitivity level (0 to 1)" }, "response_eagerness": { "type": "number", "minimum": 0, "maximum": 1, "description": "How eagerly the agent responds (0 to 1). Only applied when transcriber is Soniox." }, "backchanneling": { "type": "boolean", "description": "Enable or disable backchanneling" }, "backchannel_frequency": { "type": "number", "minimum": 0, "maximum": 1, "description": "Frequency of backchannel responses", "example": 0.5 }, "transcription_mode": { "type": "string", "enum": [ "optimize_for_speed", "optimize_for_accuracy" ], "description": "Mode for transcription" }, "denoising_mode": { "type": "string", "enum": [ "remove_noise", "remove_noise_and_speech" ], "nullable": true, "description": "Mode for denoising audio input" }, "speech_normalization": { "type": "boolean", "description": "Enable or disable speech normalization" }, "transcript_formatting": { "type": "boolean", "description": "Enable or disable transcript formatting" }, "backchannel_keywords": { "type": "string", "description": "Comma-separated list of backchannel keywords" }, "boosted_keywords": { "type": "string", "description": "Comma-separated recognition hints for supported Deepgram and Soniox transcribers. Terms can contain letters, numbers, and spaces only. The normalized list supports up to 100 terms, 50 characters per term, and 2000 total characters.", "maxLength": 2000, "example": "DialNexa, Nexa Prime, customer success" }, "reminder_message_interval": { "type": "number", "description": "Interval between reminder messages (in seconds)" }, "reminder_message_frequency": { "type": "number", "description": "Frequency of reminder messages" }, "transcriber_id": { "type": "string", "nullable": true, "description": "ID of the transcriber catalog entry" }, "fallback_stt_enabled": { "type": "boolean", "description": "Enable parallel fallback STT for this agent" }, "stt_fallback_transcriber_id": { "type": "string", "nullable": true, "description": "Fallback STT transcriber catalog entry" }, "stt_fallback_wait_ms": { "type": "number", "minimum": 0, "description": "Milliseconds to wait for primary STT after fallback finalizes first" }, "audio_cache_enabled": { "type": "boolean", "description": "Enable TTS audio caching for this agent" }, "version_number": { "type": "number", "description": "Version number of the agent to update", "example": 1 }, "folder_id": { "type": "string", "description": "ID of the folder this agent belongs to", "example": "fld_abc123xyz789" }, "pipeline_type": { "type": "string", "description": "Pipeline subtype for Single_Prompt_Agent. Cascaded = ASR→LLM→TTS pipeline. Speech_To_Speech = direct speech model.", "enum": [ "Cascaded", "Speech_To_Speech" ], "example": "Cascaded" }, "title": { "type": "string", "description": "Title of the agent (max 70 characters)", "example": "Customer Support Agent", "maxLength": 70 }, "version_title": { "type": "string", "description": "Version title (optional, will be auto-generated if not provided, max 35 characters)", "example": "Version 1.1", "nullable": true, "maxLength": 35 }, "description": { "type": "string", "description": "Description of the agent", "example": "This agent handles customer support inquiries" }, "timezone": { "type": "string", "description": "Timezone for the agent", "example": "Asia/Kolkata" }, "inbound_phone_number_id": { "type": "string", "description": "ID of the inbound phone number to use for this agent. Must be an existing phone number ID in your organization. Applied to live inbound routing only when `is_published: true` is sent in the same request. Pass an empty string to detach while publishing." }, "system_prompt_text": { "type": "string", "description": "Static system instructions for the agent. Use prompt_text for dynamic content via {{variable}} syntax.", "example": "You are a helpful customer support agent named Sarah." }, "outbound_phone_number_id": { "type": "string", "description": "ID of the outbound phone number to use for this agent. Must be an existing phone number ID in your organization. Applied to live outbound routing only when `is_published: true` is sent in the same request. Pass an empty string to detach while publishing. Active workflows using the number can cause a 409 conflict." }, "language_id": { "type": "string", "description": "ID of the language the agent speaks", "example": "lng_59a9ce4a91334686933a" }, "llm_id": { "type": "string", "description": "ID of the LLM associated with the agent", "example": "A1B2C3D4E5F6G7" }, "llm_temperature": { "type": "number", "description": "temperature value for the LLM which controls how creative the model responses are", "example": 0.1, "default": 0.1 }, "voice_id": { "type": "string", "description": "ID of the voice used by the agent", "example": "VOICE123456789" }, "webhook_id": { "type": "string", "description": "ID of the webhook associated with the agent", "example": "wh_12345678901234" }, "prompt_text": { "type": "string", "description": "Main instructions for the agent. Supports Handlebars template syntax such as {{variable}} for dynamic content. Must be valid Handlebars template text.", "example": "Hello, how can I assist you today?" }, "node_positions": { "type": "string", "description": "Node positions for Conversational_Flow_Agent type (stored as JSON string)", "example": "{\"id\" : 1, \"positions\" : {\"x\": 100, \"y\": 200}}" }, "conversation_start_type": { "type": "string", "description": "Who starts the conversation", "example": "user", "enum": [ "user", "agent_dynamic", "agent_defined" ] }, "welcome_message": { "type": "string", "description": "Opening message spoken by the agent at the start of the call. Supports Handlebars template syntax such as {{variable}} and must be valid Handlebars template text.", "example": "Welcome to our service!" }, "allow_interruptions": { "type": "boolean", "description": "Whether the agent allows interruptions", "example": true }, "structured_output": { "type": "boolean", "description": "Whether the reponse should adhere to a structure or not", "example": true }, "json_output_instructions": { "type": "object", "description": "Instructions for JSON output", "example": { "format": "detailed" } }, "knowledge_base_ids": { "description": "IDs of the knowledge bases attached to this agent version", "example": [ "kb_abc123", "kb_def456" ], "type": "array", "items": { "type": "string" } }, "kb_max_chunks": { "type": "number", "description": "Maximum number of RAG chunks to fetch (1-10)", "example": 5, "minimum": 1, "maximum": 10 }, "kb_min_score": { "type": "number", "description": "Minimum similarity score threshold for RAG results (0-1)", "example": 0.5, "minimum": 0, "maximum": 1 }, "is_published": { "type": "boolean", "description": "Publish this draft version. When true, phone number IDs in the same request are claimed for live routing.", "example": false }, "update_deployment": { "type": "boolean", "description": "Whether to allow updating a published version", "example": false }, "default_dynamic_variables": { "type": "object", "description": "Default values for dynamic variables used in Handlebars templates. For call-transfer flows, agent_transfer_destinations accepts up to 7 pipe-separated phone numbers. Each number must use US +1 or India +91 and exactly 10 digits after the country code.", "example": { "firstName": "John", "lastName": "Doe", "courseType": "Math" } }, "fallback_llm_enabled": { "type": "boolean", "description": "Enable fallback LLM for this agent", "example": false }, "llm_fallback_delay_ms": { "type": "number", "description": "Milliseconds to wait before triggering the fallback LLM", "example": 500, "nullable": true }, "llm_fallback_model": { "type": "string", "description": "ID (llms.id) of the LLM to use as fallback", "example": "abc123xyz789ab", "nullable": true }, "predictive_preprocessing_enabled": { "type": "boolean", "description": "Enable predictive preprocessing for this agent version", "example": false }, "voice_model_id": { "type": "string", "description": "Speech synthesis model for the selected voice. The model must belong to the same provider as voice_id. Omit this field when you want DialNexa to apply the recommended model. For ElevenLabs voices, use eleven_flash_v2_5 where supported. To find supported models for one voice, call GET /v1/voices/{voice_id}/voice-models.", "example": "254" }, "agent_identity": { "type": "string", "description": "Agent identity (required for Conversational_Flow_Agent type on update)", "example": "You are a helpful customer support agent named Sarah." }, "agent_background": { "type": "string", "description": "Agent background (required for Conversational_Flow_Agent type on update)", "example": "You have 5 years of experience in customer support and specialize in helping customers with technical issues." }, "post_call_analysis": { "description": "Post call analysis configuration", "example": [ { "field_name": "customer_satisfaction", "field_type": "NUMBER", "field_description": "Customer satisfaction rating" } ], "type": "array", "items": { "type": "object", "required": [ "field_name", "field_type", "field_description" ], "properties": { "field_name": { "type": "string" }, "field_type": { "type": "string", "enum": [ "NUMBER", "STRING", "BOOLEAN", "ENUM" ] }, "field_description": { "type": "string" } } } }, "postcall_analysis": { "description": "Post call analysis configuration (alternative field name)", "example": [ { "field_name": "customer_satisfaction", "field_type": "NUMBER", "field_description": "Customer satisfaction rating" } ], "type": "array", "items": { "type": "object", "required": [ "field_name", "field_type", "field_description" ], "properties": { "field_name": { "type": "string" }, "field_type": { "type": "string", "enum": [ "NUMBER", "STRING", "BOOLEAN", "ENUM" ] }, "field_description": { "type": "string" } } } }, "agent_functions": { "type": "array", "description": "Agent functions - full replace for this version. Pass empty array to clear all.", "items": { "type": "object", "properties": { "displayName": { "type": "string", "example": "Book Calendar" }, "type": { "type": "string", "enum": [ "end_call", "call_transfer", "custom", "check_calendar_availability", "book_calendar", "integration" ] }, "description": { "type": "string", "example": "Book appointments" }, "config": { "type": "object", "example": { "api_key": "xxx" } } } } }, "post_call_analysis_llm_id": { "type": "string", "nullable": true, "description": "LLM ID used for post-call analysis extraction. Pass a signed LLM ID such as llm_A1B2C3D4E5F6G7 to set an override, null to clear it, or omit the field to leave the existing setting unchanged.", "example": "llm_A1B2C3D4E5F6G7" }, "prompt_caching_enabled": { "type": "boolean", "description": "Enable OpenAI Prompt Caching for this agent version. DialNexa must enable this feature for your workspace.", "example": false } }, "required": [ "version_number" ] }, "UpdateKnowledgeBaseRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the knowledge base", "example": "Updated Product Documentation" } } }, "UpdateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "example": "https://webhook.site/updated-endpoint", "description": "The new URL for the webhook." }, "events": { "example": [ "order.paid" ], "description": "Updated list of events.", "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean", "example": false, "description": "Whether the webhook is active." }, "secret": { "type": "string", "example": "newSecret", "description": "New secret for signing payloads." } } } } } }