{
"openapi": "3.1.0",
"info": {
"title": "UponAI Public API",
"version": "2026-04-20",
"description": "Customer API for agents, conversations, calls, knowledge, and voices. Authenticate with a dashboard-generated bearer token and use GET /api/v1/workspaces to discover accessible workspaces."
},
"servers": [
{
"url": "https://api.upon-ai.com"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "LLM Models",
"description": "Manage reusable large language model configurations for agents."
},
{
"name": "Agents",
"description": "Configure agents that power calls and web sessions."
},
{
"name": "Chat Agents",
"description": "Configure reusable chat-first agents for website, messaging, and embedded experiences."
},
{
"name": "Chats",
"description": "Create and manage live chat sessions, completions, and outbound SMS conversations."
},
{
"name": "Chat Widgets",
"description": "Create embeddable, white-labeled website chat widgets backed by UponAI chat agents."
},
{
"name": "Conversation Flows",
"description": "Build and maintain reusable dialog graphs for agents."
},
{
"name": "Knowledge Bases",
"description": "Store and curate grounded knowledge sources."
},
{
"name": "Voices",
"description": "Discover and manage speech synthesis voices available to a workspace."
},
{
"name": "Test Case Definitions",
"description": "Create and manage simulation test case definitions for response engines."
},
{
"name": "Batch Tests",
"description": "Create and inspect simulation batch jobs across saved test cases."
},
{
"name": "Test Runs",
"description": "Retrieve test execution results and batch run histories."
},
{
"name": "Account",
"description": "Account level utilities and limits."
},
{
"name": "Calls",
"description": "Initiate and manage UponAI powered voice and web calls."
}
],
"paths": {
"/api/v1/llms": {
"get": {
"summary": "List LLMs",
"description": "Enumerate the UponAI LLM configurations available to a workspace. Results are returned newest first.\n",
"tags": [
"LLM Models"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/LimitQuery"
},
{
"$ref": "#/components/parameters/PaginationKeyQuery"
},
{
"$ref": "#/components/parameters/PaginationKeyVersionQuery"
}
],
"responses": {
"200": {
"description": "LLM configurations visible to the workspace.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LlmSummary"
}
},
"examples": {
"default": {
"value": [
{
"llm_id": "llm_1ab234cde567fgh",
"display_name": "Concierge v2",
"version": 3
},
{
"llm_id": "llm_9xy654zba321cde",
"display_name": "Outbound Collections",
"version": 5
}
]
}
}
}
}
}
},
"operationId": "listLlms",
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"summary": "Create LLM",
"description": "Provision a new UponAI large language model configuration.",
"tags": [
"LLM Models"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateLlmRequest"
},
"examples": {
"coldStatic": {
"summary": "Cold transfer to a fixed number",
"value": {
"workspaceId": 42,
"display_name": "Concierge with cold transfer",
"model": "gpt-4o-mini",
"general_prompt": "You are the voice of UponAI. Help callers and transfer them when needed.",
"begin_message": "Hi there! Thanks for calling.",
"responsiveness": "fast",
"general_tools": [
{
"type": "transfer_call",
"name": "transfer_to_support",
"description": "Transfer the caller to support when they ask for a human.",
"transfer_destination": {
"type": "predefined",
"number": "+18885551212"
},
"transfer_option": {
"type": "cold_transfer",
"cold_transfer_mode": "sip_invite",
"show_transferee_as_caller": false
}
}
]
}
},
"coldSipInvite": {
"summary": "Cold transfer using SIP INVITE",
"value": {
"workspaceId": 42,
"display_name": "Sales SIP INVITE transfer",
"model": "gpt-4o-mini",
"general_prompt": "Route qualified sales callers to the sales queue.",
"general_tools": [
{
"type": "transfer_call",
"name": "transfer_to_sales",
"description": "Transfer qualified sales callers to the sales team.",
"transfer_destination": {
"type": "predefined",
"number": "+18885550100"
},
"transfer_option": {
"type": "cold_transfer",
"cold_transfer_mode": "sip_invite",
"show_transferee_as_caller": true
},
"custom_sip_headers": {
"x-department": "sales"
}
}
]
}
},
"coldSipRefer": {
"summary": "Cold transfer using SIP REFER",
"value": {
"workspaceId": 42,
"display_name": "Carrier SIP REFER transfer",
"model": "gpt-4o-mini",
"general_prompt": "Transfer callers to the carrier PBX using SIP REFER when requested.",
"general_tools": [
{
"type": "transfer_call",
"name": "refer_to_pbx",
"description": "Use SIP REFER to send the caller to the PBX destination.",
"transfer_destination": {
"type": "predefined",
"number": "+18885550101"
},
"transfer_option": {
"type": "cold_transfer",
"cold_transfer_mode": "sip_refer"
},
"custom_sip_headers": {
"Refer-To": "sip:support@pbx.example.com"
}
}
]
}
},
"warmTransfer": {
"summary": "Warm transfer with handoff prompts",
"value": {
"workspaceId": 42,
"display_name": "Concierge warm transfer",
"model": "gpt-4o-mini",
"general_prompt": "Help the caller, then warm transfer to a live teammate when requested.",
"general_tools": [
{
"type": "transfer_call",
"name": "warm_transfer_to_support",
"description": "Warm transfer the caller to support after confirming the reason.",
"transfer_destination": {
"type": "predefined",
"number": "+18885551212"
},
"transfer_option": {
"type": "warm_transfer",
"show_transferee_as_caller": false,
"agent_detection_timeout_ms": 30000,
"transfer_ring_duration_ms": 30000,
"on_hold_music": "relaxing_sound",
"public_handoff_option": {
"type": "prompt",
"prompt": "Summarize the caller's issue in one sentence before bridging."
},
"private_handoff_option": {
"type": "static_message",
"message": "Caller is ready to speak with support."
},
"enable_bridge_audio_cue": true
}
}
]
}
},
"agenticWarmTransfer": {
"summary": "Agentic warm transfer",
"value": {
"workspaceId": 42,
"display_name": "Agentic transfer router",
"model": "gpt-4o-mini",
"general_prompt": "Start transfer screening with a dedicated transfer agent before bridging.",
"general_tools": [
{
"type": "transfer_call",
"name": "agentic_warm_transfer_to_support",
"description": "Let a transfer agent screen the destination before bridging the caller.",
"transfer_destination": {
"type": "predefined",
"number": "+18885551212"
},
"transfer_option": {
"type": "agentic_warm_transfer",
"show_transferee_as_caller": false,
"on_hold_music": "relaxing_sound",
"transfer_ring_duration_ms": 30000,
"public_handoff_option": {
"type": "prompt",
"prompt": "Tell both sides that you are connecting them now."
},
"agentic_transfer_config": {
"transfer_agent": {
"agent_id": "agent_transfer_screening_123",
"agent_version": 0
},
"transfer_timeout_ms": 30000,
"action_on_timeout": "cancel_transfer"
},
"enable_bridge_audio_cue": true
}
}
]
}
},
"inferredDestination": {
"summary": "AI-inferred transfer destination",
"value": {
"workspaceId": 42,
"display_name": "Department router",
"model": "gpt-4o-mini",
"general_prompt": "Identify which department the caller needs and transfer accordingly.",
"general_tools": [
{
"type": "transfer_call",
"name": "transfer_to_department",
"description": "Transfer to billing, sales, or support based on the caller's request.",
"transfer_destination": {
"type": "inferred",
"prompt": "Transfer to billing at +18885550111, sales at +18885550112, or support at +18885550113 based on the user's request."
},
"transfer_option": {
"type": "cold_transfer",
"cold_transfer_mode": "sip_invite"
}
}
]
}
},
"multiPrompt": {
"summary": "Multiprompt LLM with state-level transfer",
"value": {
"workspaceId": 42,
"display_name": "Multiprompt transfer workflow",
"model": "gpt-4o-mini",
"general_prompt": "You are a helpful phone assistant.",
"starting_state": "intake",
"states": [
{
"name": "intake",
"state_prompt": "Ask what the caller needs, then transfer sales callers.",
"tools": [
{
"type": "transfer_call",
"name": "transfer_sales",
"description": "Transfer callers who want to buy or upgrade.",
"transfer_destination": {
"type": "predefined",
"number": "{{transfer_destination}}"
},
"transfer_option": {
"type": "cold_transfer",
"cold_transfer_mode": "sip_invite"
}
}
]
}
]
}
}
}
}
}
},
"responses": {
"201": {
"description": "Newly created LLM configuration.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Llm"
},
"examples": {
"default": {
"value": {
"llm_id": "llm_1ab234cde567fgh",
"display_name": "Concierge v2",
"version": 1,
"model": "gpt-4o-mini",
"general_prompt": "You are the voice of UponAI...",
"begin_message": "Hi there! Thanks for calling UponAI.",
"updated_at": "2025-02-08T17:21:34.000Z"
}
}
}
}
}
}
},
"operationId": "createLlm",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/llms/{llmId}": {
"parameters": [
{
"$ref": "#/components/parameters/LlmIdPath"
}
],
"get": {
"summary": "Get LLM",
"description": "Retrieve the latest or a specific version of an LLM configuration.",
"tags": [
"LLM Models"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/VersionQuery"
}
],
"responses": {
"200": {
"description": "LLM configuration details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Llm"
}
}
}
}
},
"operationId": "getLlm",
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"summary": "Update LLM",
"description": "Apply partial updates to an existing LLM configuration.",
"tags": [
"LLM Models"
],
"parameters": [
{
"$ref": "#/components/parameters/VersionQuery"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateLlmRequest"
}
}
}
},
"responses": {
"200": {
"description": "Updated LLM configuration.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Llm"
}
}
}
}
},
"operationId": "updateLlm",
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"summary": "Delete LLM",
"description": "Permanently delete an LLM configuration and its versions.",
"tags": [
"LLM Models"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"204": {
"description": "LLM deleted."
}
},
"operationId": "deleteLlm",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/agents": {
"get": {
"summary": "List agents",
"description": "List agents created inside a workspace.",
"tags": [
"Agents"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/LimitQuery"
},
{
"$ref": "#/components/parameters/PaginationKeyQuery"
},
{
"$ref": "#/components/parameters/PaginationKeyVersionQuery"
}
],
"responses": {
"200": {
"description": "Agent summary list.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentSummary"
}
}
}
}
}
},
"operationId": "listAgents",
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"summary": "Create agent",
"description": "Create a new UponAI agent for use in calls and web sessions.",
"tags": [
"Agents"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAgentRequest"
}
}
}
},
"responses": {
"201": {
"description": "Newly created agent.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Agent"
}
}
}
}
},
"operationId": "createAgent",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/agents/{agentId}": {
"parameters": [
{
"$ref": "#/components/parameters/AgentIdPath"
}
],
"get": {
"summary": "Get agent",
"description": "Retrieve the active configuration or a historical version of an agent.",
"tags": [
"Agents"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/VersionQuery"
}
],
"responses": {
"200": {
"description": "Agent configuration.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Agent"
}
}
}
}
},
"operationId": "getAgent",
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"summary": "Update agent",
"description": "Apply partial updates to an existing agent configuration.",
"tags": [
"Agents"
],
"parameters": [
{
"$ref": "#/components/parameters/VersionQuery"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAgentRequest"
}
}
}
},
"responses": {
"200": {
"description": "Updated agent.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Agent"
}
}
}
}
},
"operationId": "updateAgent",
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"summary": "Delete agent",
"description": "Permanently remove an agent and all saved versions.",
"tags": [
"Agents"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"204": {
"description": "Agent deleted."
}
},
"operationId": "deleteAgent",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/agents/{agentId}/versions": {
"parameters": [
{
"$ref": "#/components/parameters/AgentIdPath"
}
],
"get": {
"summary": "List agent versions",
"description": "Review the revision history for an agent.",
"tags": [
"Agents"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Agent version history.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentVersion"
}
}
}
}
}
},
"operationId": "listAgentVersions",
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"summary": "Create agent draft version",
"description": "Create a new editable draft from an existing agent version.",
"tags": [
"Agents"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAgentVersionRequest"
}
}
}
},
"responses": {
"201": {
"description": "Draft version created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Agent"
}
}
}
}
},
"operationId": "createAgentDraftVersion",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/agents/{agentId}/versions/{version}/publish": {
"parameters": [
{
"$ref": "#/components/parameters/AgentIdPath"
},
{
"$ref": "#/components/parameters/VersionPath"
}
],
"post": {
"summary": "Publish agent version",
"description": "Publish one existing draft version in place.",
"tags": [
"Agents"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublishAgentVersionRequest"
}
}
}
},
"responses": {
"200": {
"description": "Published agent version.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Agent"
}
}
}
}
},
"operationId": "publishAgentVersion",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/agents/{agentId}/versions/{version}": {
"parameters": [
{
"$ref": "#/components/parameters/AgentIdPath"
},
{
"$ref": "#/components/parameters/VersionPath"
}
],
"delete": {
"summary": "Delete agent version",
"description": "Delete one specific agent version.",
"tags": [
"Agents"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"204": {
"description": "Agent version deleted."
}
},
"operationId": "deleteAgentVersion",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chat-agents": {
"get": {
"summary": "List chat agents",
"description": "List chat agents created inside a workspace.",
"tags": [
"Chat Agents"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/LimitQuery"
},
{
"$ref": "#/components/parameters/PaginationKeyQuery"
},
{
"$ref": "#/components/parameters/PaginationKeyVersionQuery"
}
],
"responses": {
"200": {
"description": "Chat agent summary list.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatAgentListResponse"
},
"examples": {
"default": {
"value": {
"data": [
{
"agent_id": "chat_agent_01hzk4q6dr3n0d4qzpw9z6gth6",
"agent_name": "Website Concierge",
"version": 3,
"response_engine": {
"type": "uponai-llm",
"llm_id": "llm_1ab234cde567fgh"
},
"auto_close_message": "Thanks for chatting with UponAI.",
"is_public": true
}
],
"pagination_key": "chat_agent_01hzk4q6dr3n0d4qzpw9z6gth6",
"pagination_key_version": 3
}
}
}
}
}
}
},
"operationId": "listChatAgents",
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"summary": "Create chat agent",
"description": "Create a new UponAI chat agent for browser and messaging use cases.",
"tags": [
"Chat Agents"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateChatAgentRequest"
},
"examples": {
"default": {
"value": {
"workspaceId": 42,
"agent_name": "Website Concierge",
"response_engine": {
"type": "uponai-llm",
"llm_id": "llm_1ab234cde567fgh"
},
"auto_close_message": "Thanks for chatting with UponAI.",
"end_chat_after_silence_ms": 600000,
"webhook_url": "https://example.com/hooks/chat-events",
"webhook_events": [
"chat_started",
"chat_ended",
"chat_analyzed"
],
"timezone": "America/New_York",
"is_public": true,
"data_storage_setting": "everything_except_pii",
"data_storage_retention_days": 30,
"post_chat_analysis_model": "gpt-4.1-mini",
"post_chat_analysis_data": [
{
"type": "chat_summary",
"name": "summary",
"description": "Short summary of the completed chat."
}
],
"uponai_dynamic_variables": {
"customer_tier": "enterprise"
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Newly created chat agent.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatAgent"
}
}
}
}
},
"operationId": "createChatAgent",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chat-agents/{agentId}": {
"parameters": [
{
"$ref": "#/components/parameters/AgentIdPath"
}
],
"get": {
"summary": "Get chat agent",
"description": "Retrieve the active configuration or a historical version of a chat agent.",
"tags": [
"Chat Agents"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/VersionQuery"
}
],
"responses": {
"200": {
"description": "Chat agent configuration.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatAgent"
}
}
}
}
},
"operationId": "getChatAgent",
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"summary": "Update chat agent",
"description": "Apply partial updates to an existing chat agent configuration.",
"tags": [
"Chat Agents"
],
"parameters": [
{
"$ref": "#/components/parameters/VersionQuery"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateChatAgentRequest"
},
"examples": {
"default": {
"value": {
"workspaceId": 42,
"agent_name": "Website Concierge Draft",
"auto_close_message": "I can follow up again whenever you need.",
"is_public": false,
"handbook_config": {
"enabled": true,
"include_sections": [
"escalation",
"billing"
]
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Updated chat agent.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatAgent"
}
}
}
}
},
"operationId": "updateChatAgent",
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"summary": "Delete chat agent",
"description": "Permanently remove a chat agent and all saved versions.",
"tags": [
"Chat Agents"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"204": {
"description": "Chat agent deleted."
}
},
"operationId": "deleteChatAgent",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chat-agents/{agentId}/versions": {
"parameters": [
{
"$ref": "#/components/parameters/AgentIdPath"
}
],
"get": {
"summary": "List chat agent versions",
"description": "Review the revision history for a chat agent.",
"tags": [
"Chat Agents"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Chat agent version history.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatAgentVersionListResponse"
}
}
}
}
},
"operationId": "listChatAgentVersions",
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"summary": "Create chat agent draft version",
"description": "Create a new editable draft from an existing chat agent version.",
"tags": [
"Chat Agents"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateAgentVersionRequest"
}
}
}
},
"responses": {
"201": {
"description": "Draft version created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatAgent"
}
}
}
}
},
"operationId": "createChatAgentDraftVersion",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chat-agents/{agentId}/versions/{version}/publish": {
"parameters": [
{
"$ref": "#/components/parameters/AgentIdPath"
},
{
"$ref": "#/components/parameters/VersionPath"
}
],
"post": {
"summary": "Publish chat agent version",
"description": "Publish one existing chat agent draft version in place.",
"tags": [
"Chat Agents"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PublishAgentVersionRequest"
}
}
}
},
"responses": {
"200": {
"description": "Published chat agent version.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatAgent"
}
}
}
}
},
"operationId": "publishChatAgentVersion",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chat-agents/{agentId}/versions/{version}": {
"parameters": [
{
"$ref": "#/components/parameters/AgentIdPath"
},
{
"$ref": "#/components/parameters/VersionPath"
}
],
"delete": {
"summary": "Delete chat agent version",
"description": "Delete one specific chat agent version.",
"tags": [
"Chat Agents"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"204": {
"description": "Chat agent version deleted."
}
},
"operationId": "deleteChatAgentVersion",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chat-agents/{agentId}/publish": {
"parameters": [
{
"$ref": "#/components/parameters/AgentIdPath"
}
],
"post": {
"summary": "Publish chat agent version (legacy path)",
"description": "Deprecated compatibility path. Publish the explicit version supplied in the request body.",
"tags": [
"Chat Agents"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"workspaceId",
"version"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"version": {
"type": "integer",
"minimum": 0
},
"versionTitle": {
"type": "string"
},
"versionDescription": {
"type": "string"
}
}
},
"examples": {
"default": {
"value": {
"workspaceId": 42,
"version": 3
}
}
}
}
}
},
"responses": {
"200": {
"description": "Published chat agent.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatAgent"
}
}
}
}
},
"deprecated": true,
"operationId": "publishChatAgentVersionFiltered",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chats": {
"get": {
"summary": "List chats",
"description": "List chats for a workspace, newest first by default.",
"tags": [
"Chats"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/SortOrderQuery"
},
{
"$ref": "#/components/parameters/LimitQuery"
},
{
"$ref": "#/components/parameters/PaginationKeyQuery"
}
],
"responses": {
"200": {
"description": "Chat session list.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatListResponse"
},
"examples": {
"default": {
"value": {
"data": [
{
"chatId": "chat_01hyz9nyrjj0x6b2n2kgq34pq7",
"agentId": "chat_agent_01hzk4q6dr3n0d4qzpw9z6gth6",
"version": 3,
"status": "ongoing",
"type": "web_chat",
"metadata": {
"source": "pricing-page"
},
"customAttributes": {
"customerId": "cust_123"
},
"startedAt": "2026-04-20T14:10:00.000Z",
"endedAt": null,
"transcript": null,
"messages": [],
"chatCost": null,
"chatAnalysis": null,
"collectedDynamicVariables": {},
"uponai_dynamic_variables": {
"customer_tier": "enterprise"
}
}
],
"pagination_key": "chat_01hyz9nyrjj0x6b2n2kgq34pq7"
}
}
}
}
}
}
},
"operationId": "listChats",
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"summary": "Create chat",
"description": "Start a new live chat session backed by a chat agent.",
"tags": [
"Chats"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateChatRequest"
},
"examples": {
"default": {
"value": {
"workspaceId": 42,
"agent_id": "chat_agent_01hzk4q6dr3n0d4qzpw9z6gth6",
"metadata": {
"source": "website",
"page": "/pricing"
},
"uponai_dynamic_variables": {
"customer_tier": "enterprise"
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Chat created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Chat"
}
}
}
}
},
"operationId": "createChat",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chats/outbound-sms": {
"post": {
"summary": "Create outbound SMS chat",
"description": "Start an outbound SMS chat session for a workspace.",
"tags": [
"Chats"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateOutboundSmsChatRequest"
},
"examples": {
"default": {
"value": {
"workspaceId": 42,
"agent_id": "chat_agent_01hzk4q6dr3n0d4qzpw9z6gth6",
"from_number": "+14155550100",
"to_number": "+14155550199",
"metadata": {
"campaign": "reactivation"
},
"uponai_dynamic_variables": {
"customer_first_name": "Jamie"
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Outbound SMS chat created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Chat"
}
}
}
}
},
"operationId": "createOutboundSmsChat",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chats/{chatId}": {
"parameters": [
{
"$ref": "#/components/parameters/ChatIdPath"
}
],
"get": {
"summary": "Get chat",
"description": "Retrieve details for a specific chat session.",
"tags": [
"Chats"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Chat details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Chat"
}
}
}
}
},
"operationId": "getChat",
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"summary": "Update chat",
"description": "Update metadata, custom attributes, or dynamic-variable overrides for an existing chat.",
"tags": [
"Chats"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateChatRequest"
},
"examples": {
"default": {
"value": {
"workspaceId": 42,
"metadata": {
"followUpOwner": "support"
},
"custom_attributes": {
"customerId": "cust_123"
},
"override_dynamic_variables": {
"discount_code": "SPRING15"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Updated chat session.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Chat"
}
}
}
}
},
"operationId": "updateChat",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chats/{chatId}/completions": {
"parameters": [
{
"$ref": "#/components/parameters/ChatIdPath"
}
],
"post": {
"summary": "Create chat completion",
"description": "Send a user message into an existing chat and receive the assistant response messages.",
"tags": [
"Chats"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateChatCompletionRequest"
},
"examples": {
"default": {
"value": {
"workspaceId": 42,
"content": "Can you send me pricing for the enterprise plan?"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Chat completion messages.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatCompletionResponse"
}
}
}
}
},
"operationId": "createChatCompletion",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chats/{chatId}/end": {
"parameters": [
{
"$ref": "#/components/parameters/ChatIdPath"
}
],
"post": {
"summary": "End chat",
"description": "Mark a chat as completed and close the session.",
"tags": [
"Chats"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "integer"
}
}
},
"examples": {
"default": {
"value": {
"workspaceId": 42
}
}
}
}
}
},
"responses": {
"204": {
"description": "Chat ended."
}
},
"operationId": "endChat",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chat-widgets": {
"get": {
"summary": "List chat widgets",
"description": "List embeddable website chat widget configurations for a workspace.",
"tags": [
"Chat Widgets"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Chat widget configurations.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatWidgetConfig"
}
},
"examples": {
"default": {
"value": [
{
"id": 12,
"publicKey": "upon_widget_7d41a8d0c84f4d1fbf8ad4f1",
"workspaceId": 42,
"agentId": "chat_agent_01hzk4q6dr3n0d4qzpw9z6gth6",
"agentVersion": null,
"title": "How can we help?",
"themeColor": "#071a3e",
"componentColor": "#2563eb",
"fabText": "Need help?",
"botName": "Support",
"popupMessage": "Questions? We are here.",
"showAiPopup": true,
"showAiPopupTime": 5,
"autoOpen": false,
"allowedOrigins": [
"https://example.com"
],
"isEnabled": true,
"embedScript": ""
}
]
}
}
}
}
}
},
"operationId": "listChatWidgets",
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"summary": "Create chat widget",
"description": "Create a public widget key and embed configuration for a website chat widget. The returned `embedScript` is the snippet to place on the customer's website. Browser traffic uses the widget public key and calls UponAI runtime endpoints; provider credentials and provider URLs are never exposed to the website.\n",
"tags": [
"Chat Widgets"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateChatWidgetRequest"
},
"examples": {
"default": {
"value": {
"workspaceId": 42,
"agentId": "chat_agent_01hzk4q6dr3n0d4qzpw9z6gth6",
"title": "How can we help?",
"fabText": "Need help?",
"botName": "Support",
"popupMessage": "Questions? We are here.",
"themeColor": "#071a3e",
"componentColor": "#2563eb",
"allowedOrigins": [
"https://example.com"
]
}
}
}
}
}
},
"responses": {
"201": {
"description": "Chat widget created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatWidgetConfig"
},
"examples": {
"default": {
"value": {
"id": 12,
"publicKey": "upon_widget_7d41a8d0c84f4d1fbf8ad4f1",
"workspaceId": 42,
"agentId": "chat_agent_01hzk4q6dr3n0d4qzpw9z6gth6",
"agentVersion": null,
"title": "How can we help?",
"logoUrl": null,
"themeColor": "#071a3e",
"componentColor": "#2563eb",
"fabText": "Need help?",
"botName": "Support",
"popupMessage": "Questions? We are here.",
"showAiPopup": true,
"showAiPopupTime": 5,
"autoOpen": false,
"allowedOrigins": [
"https://example.com"
],
"metadata": {},
"isEnabled": true,
"embedScript": ""
}
}
}
}
}
}
},
"operationId": "createChatWidget",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chat-widgets/{widgetId}": {
"parameters": [
{
"$ref": "#/components/parameters/WidgetIdPath"
}
],
"get": {
"summary": "Get chat widget",
"description": "Retrieve a website chat widget configuration and its embed script.",
"tags": [
"Chat Widgets"
],
"responses": {
"200": {
"description": "Chat widget configuration.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatWidgetConfig"
}
}
}
}
},
"operationId": "getChatWidget",
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"summary": "Update chat widget",
"description": "Update styling, allowed origins, assigned chat agent, or enabled state for a website widget.",
"tags": [
"Chat Widgets"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateChatWidgetRequest"
},
"examples": {
"default": {
"value": {
"title": "Chat with us",
"fabText": "Questions?",
"componentColor": "#2563eb",
"allowedOrigins": [
"https://example.com",
"https://www.example.com"
],
"isEnabled": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Updated chat widget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatWidgetConfig"
}
}
}
}
},
"operationId": "updateChatWidget",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/chat-widgets/{widgetId}/regenerate-key": {
"parameters": [
{
"$ref": "#/components/parameters/WidgetIdPath"
}
],
"post": {
"summary": "Regenerate widget key",
"description": "Rotate the public widget key. Existing website embeds using the old key will stop working until the script tag is updated with the returned `embedScript`.\n",
"tags": [
"Chat Widgets"
],
"responses": {
"200": {
"description": "Chat widget with a new public key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChatWidgetConfig"
}
}
}
}
},
"operationId": "regenerateWidgetKey",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/conversation-flows": {
"get": {
"summary": "List conversation flows",
"description": "Enumerate conversation flows for the workspace.",
"tags": [
"Conversation Flows"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/LimitQuery"
},
{
"$ref": "#/components/parameters/PaginationKeyQuery"
},
{
"$ref": "#/components/parameters/PaginationKeyVersionQuery"
}
],
"responses": {
"200": {
"description": "Conversation flow summaries.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConversationFlowSummary"
}
}
}
}
}
},
"operationId": "listConversationFlows",
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"summary": "Create conversation flow",
"description": "Compose a reusable flow graph for agents to attach to.",
"tags": [
"Conversation Flows"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateConversationFlowRequest"
}
}
}
},
"responses": {
"201": {
"description": "Newly created conversation flow.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationFlow"
}
}
}
}
},
"operationId": "createConversationFlow",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/conversation-flows/{conversationFlowId}": {
"parameters": [
{
"$ref": "#/components/parameters/ConversationFlowIdPath"
}
],
"get": {
"summary": "Get conversation flow",
"description": "Retrieve the latest or a specific version of a conversation flow.",
"tags": [
"Conversation Flows"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/VersionQuery"
}
],
"responses": {
"200": {
"description": "Conversation flow details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationFlow"
}
}
}
}
},
"operationId": "getConversationFlow",
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"summary": "Update conversation flow",
"description": "Apply partial updates to a conversation flow.",
"tags": [
"Conversation Flows"
],
"parameters": [
{
"$ref": "#/components/parameters/VersionQuery"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateConversationFlowRequest"
}
}
}
},
"responses": {
"200": {
"description": "Updated conversation flow.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationFlow"
}
}
}
}
},
"operationId": "updateConversationFlow",
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"summary": "Delete conversation flow",
"description": "Remove a conversation flow and its versions.",
"tags": [
"Conversation Flows"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"204": {
"description": "Conversation flow deleted."
}
},
"operationId": "deleteConversationFlow",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/knowledge-bases": {
"get": {
"summary": "List knowledge bases",
"description": "Enumerate knowledge bases available to the workspace.",
"tags": [
"Knowledge Bases"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Knowledge base summaries.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KnowledgeBaseSummary"
}
}
}
}
}
},
"operationId": "listKnowledgeBases",
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"summary": "Create knowledge base",
"description": "Create a knowledge base and ingest documents, URLs, or free-form text for grounded responses. URL auto-refresh and chunking controls are supported when needed.\n",
"tags": [
"Knowledge Bases"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateKnowledgeBaseRequest"
}
}
}
},
"responses": {
"201": {
"description": "Newly created knowledge base.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeBase"
}
}
}
}
},
"operationId": "createKnowledgeBase",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/knowledge-bases/{knowledgeBaseId}": {
"parameters": [
{
"$ref": "#/components/parameters/KnowledgeBaseIdPath"
}
],
"get": {
"summary": "Get knowledge base",
"description": "Retrieve knowledge base metadata and ingestion status.",
"tags": [
"Knowledge Bases"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Knowledge base details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeBase"
}
}
}
}
},
"operationId": "getKnowledgeBase",
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"summary": "Delete knowledge base",
"description": "Permanently remove a knowledge base and its sources.",
"tags": [
"Knowledge Bases"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"204": {
"description": "Knowledge base deleted."
}
},
"operationId": "deleteKnowledgeBase",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/knowledge-bases/{knowledgeBaseId}/sources": {
"parameters": [
{
"$ref": "#/components/parameters/KnowledgeBaseIdPath"
}
],
"post": {
"summary": "Add knowledge base sources",
"description": "Append new source material to an existing knowledge base.",
"tags": [
"Knowledge Bases"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddKnowledgeBaseSourcesRequest"
}
}
}
},
"responses": {
"200": {
"description": "Knowledge base with updated source list.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeBase"
}
}
}
}
},
"operationId": "addKnowledgeBaseSources",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/knowledge-bases/{knowledgeBaseId}/sources/{sourceId}": {
"parameters": [
{
"$ref": "#/components/parameters/KnowledgeBaseIdPath"
},
{
"$ref": "#/components/parameters/SourceIdPath"
}
],
"delete": {
"summary": "Delete knowledge base source",
"description": "Remove a specific source entry from a knowledge base.",
"tags": [
"Knowledge Bases"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Knowledge base with updated source list.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeBase"
}
}
}
}
},
"operationId": "deleteKnowledgeBaseSource",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/voices": {
"get": {
"summary": "List voices",
"description": "Explore the UponAI voice catalog available to a workspace.",
"tags": [
"Voices"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Voice catalog.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Voice"
}
}
}
}
}
},
"operationId": "listVoices",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/voices/search": {
"post": {
"summary": "Search community voices",
"description": "Search provider voice catalogs for community voices.",
"tags": [
"Voices"
],
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchCommunityVoiceRequest"
}
}
}
},
"responses": {
"200": {
"description": "Matching community voices.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchCommunityVoiceResponse"
}
}
}
}
},
"operationId": "searchCommunityVoices",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/voices/community": {
"post": {
"summary": "Add community voice",
"description": "Add a provider community voice into the workspace library.",
"tags": [
"Voices"
],
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddCommunityVoiceRequest"
}
}
}
},
"responses": {
"200": {
"description": "Community voice added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Voice"
}
}
}
}
},
"operationId": "addCommunityVoice",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/voices/clone": {
"post": {
"summary": "Clone voice",
"description": "Clone a custom voice from uploaded source audio files.",
"tags": [
"Voices"
],
"parameters": [],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/CloneVoiceRequest"
}
}
}
},
"responses": {
"201": {
"description": "Cloned voice metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Voice"
}
}
}
}
},
"operationId": "cloneVoice",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/voices/{voiceId}": {
"parameters": [
{
"$ref": "#/components/parameters/VoiceIdPath"
}
],
"get": {
"summary": "Get voice",
"description": "Retrieve metadata for a specific voice.",
"tags": [
"Voices"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Voice metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Voice"
}
}
}
}
},
"operationId": "getVoice",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/voices/{voiceId}/sample": {
"parameters": [
{
"$ref": "#/components/parameters/VoiceIdPath"
}
],
"get": {
"summary": "Stream voice sample",
"description": "Stream an MPEG sample to preview the voice.",
"tags": [
"Voices"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Voice sample stream.",
"content": {
"audio/mpeg": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
},
"operationId": "streamVoiceSample",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/test-case-definitions": {
"get": {
"summary": "List test case definitions",
"description": "List test case definitions for a target response engine.",
"tags": [
"Test Case Definitions"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/TestCaseDefinitionTypeQuery"
},
{
"$ref": "#/components/parameters/LlmIdQuery"
},
{
"$ref": "#/components/parameters/ConversationFlowIdQuery"
},
{
"$ref": "#/components/parameters/VersionQuery"
},
{
"$ref": "#/components/parameters/LimitQuery"
},
{
"$ref": "#/components/parameters/PaginationKeyQuery"
}
],
"responses": {
"200": {
"description": "Test case definitions.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TestCaseDefinition"
}
}
}
}
}
},
"operationId": "listTestCaseDefinitions",
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"summary": "Create test case definition",
"description": "Create a simulation test case definition for a response engine.",
"tags": [
"Test Case Definitions"
],
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTestCaseDefinitionRequest"
}
}
}
},
"responses": {
"201": {
"description": "Created test case definition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TestCaseDefinition"
}
}
}
}
},
"operationId": "createTestCaseDefinition",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/batch-tests": {
"get": {
"summary": "List batch tests",
"description": "List simulation batch jobs for a target response engine.",
"tags": [
"Batch Tests"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/TestCaseDefinitionTypeQuery"
},
{
"$ref": "#/components/parameters/LlmIdQuery"
},
{
"$ref": "#/components/parameters/ConversationFlowIdQuery"
},
{
"$ref": "#/components/parameters/VersionQuery"
},
{
"$ref": "#/components/parameters/LimitQuery"
},
{
"$ref": "#/components/parameters/PaginationKeyQuery"
}
],
"responses": {
"200": {
"description": "Batch test jobs.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BatchTest"
}
}
}
}
}
},
"operationId": "listBatchTests",
"security": [
{
"bearerAuth": []
}
]
},
"post": {
"summary": "Create batch test",
"description": "Run one or more saved simulation test case definitions against a response engine.",
"tags": [
"Batch Tests"
],
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBatchTestRequest"
}
}
}
},
"responses": {
"201": {
"description": "Created batch test job.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchTest"
}
}
}
}
},
"operationId": "createBatchTest",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/batch-tests/{testCaseBatchJobId}": {
"parameters": [
{
"$ref": "#/components/parameters/TestCaseBatchJobIdPath"
}
],
"get": {
"summary": "Get batch test",
"description": "Retrieve a simulation batch job by ID.",
"tags": [
"Batch Tests"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Batch test job.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchTest"
}
}
}
}
},
"operationId": "getBatchTest",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/test-case-definitions/{testCaseDefinitionId}": {
"parameters": [
{
"$ref": "#/components/parameters/TestCaseDefinitionIdPath"
}
],
"get": {
"summary": "Get test case definition",
"description": "Retrieve a single test case definition.",
"tags": [
"Test Case Definitions"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Test case definition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TestCaseDefinition"
}
}
}
}
},
"operationId": "getTestCaseDefinition",
"security": [
{
"bearerAuth": []
}
]
},
"put": {
"summary": "Update test case definition",
"description": "Update an existing test case definition.",
"tags": [
"Test Case Definitions"
],
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTestCaseDefinitionRequest"
}
}
}
},
"responses": {
"200": {
"description": "Updated test case definition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TestCaseDefinition"
}
}
}
}
},
"operationId": "updateTestCaseDefinition",
"security": [
{
"bearerAuth": []
}
]
},
"delete": {
"summary": "Delete test case definition",
"description": "Delete an existing test case definition.",
"tags": [
"Test Case Definitions"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"204": {
"description": "Test case definition deleted."
}
},
"operationId": "deleteTestCaseDefinition",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/test-runs/{testCaseJobId}": {
"parameters": [
{
"$ref": "#/components/parameters/TestCaseJobIdPath"
}
],
"get": {
"summary": "Get test run",
"description": "Retrieve a single test run result by job ID.",
"tags": [
"Test Runs"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Test run payload.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TestRun"
}
}
}
}
},
"operationId": "getTestRun",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/test-runs/batches/{testCaseBatchJobId}": {
"parameters": [
{
"$ref": "#/components/parameters/TestCaseBatchJobIdPath"
}
],
"get": {
"summary": "List test runs by batch",
"description": "List all test runs associated with a batch job.",
"tags": [
"Test Runs"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/LimitQuery"
},
{
"$ref": "#/components/parameters/PaginationKeyQuery"
}
],
"responses": {
"200": {
"description": "Batch test runs.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TestRun"
}
}
}
}
}
},
"operationId": "listTestRunsByBatch",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/concurrency": {
"get": {
"summary": "Get concurrency",
"description": "Retrieve concurrency limits and current usage for the account.",
"tags": [
"Account"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
}
],
"responses": {
"200": {
"description": "Concurrency snapshot.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Concurrency"
}
}
}
}
},
"operationId": "getConcurrency",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/workspaces": {
"get": {
"summary": "List workspaces",
"description": "List the workspaces accessible to the bearer token. Use this endpoint to discover the workspaceId required by workspace-scoped endpoints.",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "Workspaces visible to the authenticated token.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"workspaces": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkspaceSummary"
}
}
},
"required": [
"workspaces"
]
},
"examples": {
"default": {
"value": {
"workspaces": [
{
"id": 42,
"name": "Demo Workspace",
"accountSid": "29e90072-fb58-4c6c-870a-43005115131e",
"accountPath": "demo-workspace",
"nativeTransferEnabled": false
}
]
}
}
}
}
}
}
},
"operationId": "listWorkspaces",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/calls/initiate": {
"post": {
"summary": "Create phone call",
"description": "Initiate a PSTN phone call via UponAI infrastructure. The workspace is inferred from the unique agentId. You may still send workspaceId for backward compatibility. Native-transfer workspaces expose the full per-call override surface, including agentOverride, overrideAgentVersion, customSipHeaders, and ignoreE164Validation.",
"tags": [
"Calls"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePhoneCallRequest"
},
"examples": {
"nativeTransferFull": {
"value": {
"agentId": "agent_01hzexample",
"fromNumber": "334",
"toNumber": "+14155550199",
"trunkName": "Main Sales Trunk",
"customerName": "Jamie Doe",
"ignoreE164Validation": true,
"overrideAgentVersion": 3,
"customSipHeaders": {
"X-Campaign": "spring-renewal",
"X-Case-Id": "case_123"
},
"metadata": {
"customerId": "cust_123",
"campaign": "renewal"
},
"uponai_dynamic_variables": {
"customer_name": "Jamie",
"plan_tier": "enterprise"
},
"agentOverride": {
"agent": {
"voiceId": "elevenlabs-morgan",
"maxCallDurationMs": 900000
},
"llm": {
"model": "gpt-4.1",
"beginMessage": "Hello Jamie, this is the virtual team from UponAI."
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "Call initiation response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePhoneCallResponse"
}
}
}
},
"400": {
"description": "Invalid request. Unknown fields, invalid dynamic variable values, or conflicting dynamic variable objects are rejected before dialing.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string"
},
"unknownFields": {
"type": "array",
"items": {
"type": "string"
}
},
"dynamicVariablesField": {
"type": "string"
},
"field": {
"type": "string"
},
"invalidKeys": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
},
"operationId": "createPhoneCall",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/calls/web": {
"post": {
"summary": "Create web call",
"description": "Start a browser based call session powered by an UponAI agent. The workspace is inferred from the unique agentId. You may still send workspaceId for backward compatibility.",
"tags": [
"Calls"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWebCallRequest"
}
}
}
},
"responses": {
"201": {
"description": "Web call created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebCall"
}
}
}
}
},
"operationId": "createWebCall",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/calls": {
"get": {
"summary": "List calls",
"description": "Deprecated. List calls with optional workspace, agent, status, and date filters from local call history. Use POST /api/v1/calls/list for the current cursor-compatible listing contract.\n",
"tags": [
"Calls"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQueryOptional"
},
{
"$ref": "#/components/parameters/AgentIdQuery"
},
{
"$ref": "#/components/parameters/StatusQuery"
},
{
"$ref": "#/components/parameters/FromDateQuery"
},
{
"$ref": "#/components/parameters/ToDateQuery"
},
{
"$ref": "#/components/parameters/PageQuery"
},
{
"$ref": "#/components/parameters/LimitQueryDefault20"
}
],
"responses": {
"200": {
"description": "Paginated call list.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallList"
}
}
}
}
},
"deprecated": true,
"operationId": "listCalls",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/calls/list": {
"post": {
"summary": "List calls",
"description": "List calls from local call history with the current unified pagination envelope. The response returns `items`, `has_more`, and `pagination_key`; send the returned pagination key in the next request to continue. You may include workspaceId to scope the query to one accessible workspace.\n",
"tags": [
"Calls"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V3ListCallsRequest"
},
"examples": {
"endedOutboundCalls": {
"value": {
"workspaceId": 42,
"filter_criteria": {
"call_status": {
"type": "enum",
"op": "in",
"value": [
"ended"
]
},
"direction": {
"type": "enum",
"op": "in",
"value": [
"outbound"
]
}
},
"sort_order": "descending",
"limit": 50,
"include_total": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "Calls matching the provided filters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V3ListCallsResponse"
}
}
}
},
"400": {
"description": "Invalid filter or pagination request."
}
},
"operationId": "listCallsFiltered",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/calls/history": {
"get": {
"summary": "Fetch call history",
"description": "Return paginated call history for a single workspace, including agent and workspace metadata plus optional search and date filters.",
"tags": [
"Calls"
],
"parameters": [
{
"$ref": "#/components/parameters/WorkspaceIdQuery"
},
{
"$ref": "#/components/parameters/AgentIdQuery"
},
{
"$ref": "#/components/parameters/AgentVersionQuery"
},
{
"$ref": "#/components/parameters/StatusQuery"
},
{
"$ref": "#/components/parameters/SearchQuery"
},
{
"$ref": "#/components/parameters/FromDateQuery"
},
{
"$ref": "#/components/parameters/ToDateQuery"
},
{
"$ref": "#/components/parameters/PageQuery"
},
{
"$ref": "#/components/parameters/LimitQueryDefault20"
},
{
"$ref": "#/components/parameters/IncludeArchivedQuery"
},
{
"$ref": "#/components/parameters/IncludeChildCallsQuery"
}
],
"responses": {
"200": {
"description": "Paginated call history.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallHistoryList"
},
"examples": {
"default": {
"value": {
"success": true,
"calls": [
{
"callSid": "call_123abc",
"callStatus": "ended",
"agentId": "agent_456def",
"agentVersion": 2,
"agentName": "Concierge",
"workspaceId": 42,
"workspaceName": "Demo Workspace",
"fromNumber": "+14155550100",
"toNumber": "+14155550199",
"direction": "outbound",
"customerName": "Jane Doe",
"duration": 214,
"startedAt": "2026-03-12T14:22:00.000Z",
"createdAt": "2026-03-12T14:22:01.000Z",
"updatedAt": "2026-03-12T14:25:35.000Z",
"recordingUrl": "https://cdn.example.com/recordings/call_123abc.mp3",
"sentiment": "positive",
"summary": "Customer confirmed an appointment for Friday.",
"voiceModel": "eleven_turbo_v2",
"llmModel": "gpt-4o-mini",
"telecommunicationsProvider": "twilio",
"carrierSid": "carrier_123",
"carrierName": "Primary Twilio",
"archived": false,
"costs": {
"voice": 0.09,
"llm": 0.03,
"voiceMarkup": 0.02,
"llmMarkup": 0.01,
"gross": 0.12,
"markup": 0.03,
"total": 0.15,
"markupRate": 25
}
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 184,
"pages": 10
},
"filters": {
"workspaceId": 42,
"agentId": null,
"agentVersion": null,
"status": null,
"fromDate": null,
"toDate": null,
"search": null,
"includeArchived": false,
"includeChildCalls": false
}
}
}
}
}
}
}
},
"operationId": "fetchCallHistory",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/calls/{callId}": {
"parameters": [
{
"$ref": "#/components/parameters/CallIdPath"
}
],
"get": {
"summary": "Get call",
"description": "Retrieve details for a specific call.",
"tags": [
"Calls"
],
"responses": {
"200": {
"description": "Call details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallDetail"
}
}
}
}
},
"operationId": "getCall",
"security": [
{
"bearerAuth": []
}
]
},
"patch": {
"summary": "Update call",
"description": "Update stored metadata or opt out of sensitive data storage. The API infers workspace from stored call data when available; workspaceId remains an optional backward-compatible fallback.",
"tags": [
"Calls"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateCallRequest"
}
}
}
},
"responses": {
"200": {
"description": "Updated call record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallRecord"
}
}
}
}
},
"operationId": "updateCall",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/calls/{callId}/end": {
"parameters": [
{
"$ref": "#/components/parameters/CallIdPath"
}
],
"post": {
"summary": "End live call",
"description": "Immediately ends an active voice or web call. If the call is already stored in call history, the workspace is inferred from that record; otherwise provide workspaceId in the request body so the action can be scoped to the correct workspace.\n",
"tags": [
"Calls"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallActionWorkspaceRequest"
}
}
}
},
"responses": {
"200": {
"description": "Live call ended.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EndLiveCallResponse"
}
}
}
},
"409": {
"description": "The call is no longer live."
}
},
"operationId": "endLiveCall",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/calls/{callId}/live": {
"parameters": [
{
"$ref": "#/components/parameters/CallIdPath"
}
],
"patch": {
"summary": "Update live call",
"description": "Applies runtime changes to an active call. You can override dynamic variables, metadata, and data storage setting, inject additional context, request a fresh agent response, and start or stop a listen-only audio stream while the call is in progress. These changes take effect immediately; metadata and data storage setting changes are also persisted to the call record. CamelCase and snake_case request field names are both accepted.\n",
"tags": [
"Calls"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateLiveCallRequest"
},
"examples": {
"injectContextAndNudge": {
"value": {
"fields_to_override": {
"override_dynamic_variables": {
"additional_discount": "15%"
},
"metadata": {
"customerId": "cust_123",
"ticketId": "ticket_456"
}
},
"call_control": {
"additional_context": "Customer just opened a billing support ticket.",
"trigger_response": true
}
}
},
"startListen": {
"value": {
"listen": {
"action": "start",
"url": "wss://example.com/live-audio/call_123abc",
"mixType": "mixed",
"sampleRate": 8000,
"disableBidirectionalAudio": true,
"metadata": {
"monitorSessionId": "mon_789"
}
}
}
},
"stopListen": {
"value": {
"listen": {
"action": "stop"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Live call updated.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateLiveCallResponse"
}
}
}
},
"409": {
"description": "The call is no longer live."
}
},
"operationId": "updateLiveCall",
"security": [
{
"bearerAuth": []
}
]
}
},
"/api/v1/calls/{callId}/analysis/rerun": {
"parameters": [
{
"$ref": "#/components/parameters/CallIdPath"
}
],
"put": {
"summary": "Rerun call analysis",
"description": "Reprocess post-call analysis for a completed call. If the call is already stored in call history, the workspace is inferred from that record; otherwise provide workspaceId in the request body.\n",
"tags": [
"Calls"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CallActionWorkspaceRequest"
}
}
}
},
"responses": {
"201": {
"description": "Call analysis rerun started or completed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RerunCallAnalysisResponse"
}
}
}
}
},
"operationId": "rerunCallAnalysis",
"security": [
{
"bearerAuth": []
}
]
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
},
"parameters": {
"WorkspaceIdQuery": {
"name": "workspaceId",
"in": "query",
"required": true,
"schema": {
"type": "integer"
},
"description": "Workspace identifier. Call GET /api/v1/workspaces to list workspaces accessible to your token."
},
"LimitQuery": {
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 1000
},
"description": "Maximum number of records to return."
},
"PaginationKeyQuery": {
"name": "paginationKey",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Identifier to continue pagination."
},
"PaginationKeyVersionQuery": {
"name": "paginationKeyVersion",
"in": "query",
"required": false,
"schema": {
"type": "integer"
},
"description": "Version paired with the pagination key."
},
"LlmIdPath": {
"name": "llmId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "LLM identifier."
},
"VersionQuery": {
"name": "version",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
},
"description": "Specific version to retrieve or update."
},
"AgentIdPath": {
"name": "agentId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Agent identifier."
},
"VersionPath": {
"name": "version",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 0
},
"description": "Specific agent version."
},
"SortOrderQuery": {
"name": "sortOrder",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"ascending",
"descending"
],
"default": "descending"
},
"description": "Sort direction for chat listings."
},
"ChatIdPath": {
"name": "chatId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Chat identifier."
},
"WidgetIdPath": {
"name": "widgetId",
"in": "path",
"required": true,
"schema": {
"type": "integer"
},
"description": "Chat widget configuration identifier."
},
"ConversationFlowIdPath": {
"name": "conversationFlowId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Conversation flow identifier."
},
"KnowledgeBaseIdPath": {
"name": "knowledgeBaseId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Knowledge base identifier."
},
"SourceIdPath": {
"name": "sourceId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Knowledge base source identifier."
},
"VoiceIdPath": {
"name": "voiceId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Voice identifier."
},
"TestCaseDefinitionTypeQuery": {
"name": "type",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Response engine type used by an existing test case definition."
},
"LlmIdQuery": {
"name": "llmId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "LLM identifier filter."
},
"ConversationFlowIdQuery": {
"name": "conversationFlowId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Conversation flow identifier filter."
},
"TestCaseBatchJobIdPath": {
"name": "testCaseBatchJobId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Test run batch identifier."
},
"TestCaseDefinitionIdPath": {
"name": "testCaseDefinitionId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Test case definition identifier."
},
"TestCaseJobIdPath": {
"name": "testCaseJobId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Test run job identifier."
},
"WorkspaceIdQueryOptional": {
"name": "workspaceId",
"in": "query",
"required": false,
"schema": {
"type": "integer"
},
"description": "Optional workspace identifier filter. Call GET /api/v1/workspaces to list workspaces accessible to your token."
},
"AgentIdQuery": {
"name": "agentId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter call listings to a specific agent."
},
"StatusQuery": {
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Filter calls by status."
},
"FromDateQuery": {
"name": "fromDate",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Inclusive start date for call listing filter."
},
"ToDateQuery": {
"name": "toDate",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Inclusive end date for call listing filter."
},
"PageQuery": {
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
"LimitQueryDefault20": {
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
},
"description": "Page size for list endpoints."
},
"AgentVersionQuery": {
"name": "agentVersion",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0
},
"description": "Filter call history to a specific persisted agent version captured at call time."
},
"SearchQuery": {
"name": "search",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Search by call SID, phone number, platform call ID, customer name, or agent name."
},
"IncludeArchivedQuery": {
"name": "includeArchived",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "When true, include archived calls in the response."
},
"IncludeChildCallsQuery": {
"name": "includeChildCalls",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "When true, include child calls linked to transfer or split-call workflows."
},
"CallIdPath": {
"name": "callId",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Call identifier or SID."
}
},
"schemas": {
"LlmSummary": {
"type": "object",
"properties": {
"llm_id": {
"type": "string"
},
"display_name": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"llm_id",
"display_name",
"version"
]
},
"CreateLlmRequest": {
"type": "object",
"required": [
"workspaceId",
"display_name"
],
"additionalProperties": true,
"properties": {
"workspaceId": {
"type": "integer"
},
"display_name": {
"type": "string"
},
"model": {
"type": "string"
},
"s2s_model": {
"type": "string",
"nullable": true,
"description": "Speech-to-speech model. Set either `model` or `s2s_model`, not both."
},
"general_prompt": {
"type": "string"
},
"begin_message": {
"type": "string",
"nullable": true
},
"start_speaker": {
"type": "string",
"enum": [
"user",
"agent"
]
},
"begin_after_user_silence_ms": {
"type": "integer",
"nullable": true
},
"responsiveness": {
"type": "string"
},
"model_temperature": {
"type": "number"
},
"model_high_priority": {
"type": "boolean"
},
"tool_call_strict_mode": {
"type": "boolean"
},
"knowledge_base_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"kb_config": {
"type": "object",
"additionalProperties": true
},
"general_tools": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LlmTool"
}
},
"states": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LlmState"
}
},
"starting_state": {
"type": "string",
"nullable": true
},
"default_dynamic_variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"mcps": {
"type": "array",
"items": {
"$ref": "#/components/schemas/McpConnection"
}
},
"version": {
"type": "integer",
"description": "Optional LLM version number."
}
}
},
"LlmTool": {
"oneOf": [
{
"$ref": "#/components/schemas/TransferCallTool"
},
{
"$ref": "#/components/schemas/EndCallTool"
},
{
"$ref": "#/components/schemas/BridgeTransferTool"
},
{
"$ref": "#/components/schemas/CancelTransferTool"
},
{
"$ref": "#/components/schemas/CustomFunctionTool"
},
{
"$ref": "#/components/schemas/Tool"
}
],
"discriminator": {
"propertyName": "type"
}
},
"TransferCallTool": {
"type": "object",
"required": [
"type",
"name",
"transfer_destination",
"transfer_option"
],
"properties": {
"type": {
"type": "string",
"enum": [
"transfer_call"
]
},
"name": {
"type": "string",
"example": "transfer_to_support"
},
"description": {
"type": "string",
"description": "Prompt-style description that tells the LLM when to call this transfer tool."
},
"transfer_destination": {
"$ref": "#/components/schemas/TransferDestination"
},
"transfer_option": {
"$ref": "#/components/schemas/TransferOption"
},
"ignore_e164_validation": {
"type": "boolean",
"description": "Disable E.164 validation for internal or custom telephony destinations."
},
"custom_sip_headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "SIP headers sent with the outbound transfer leg.",
"example": {
"x-department": "support"
}
},
"speak_during_execution": {
"type": "boolean"
},
"execution_message_description": {
"type": "string"
},
"execution_message_type": {
"type": "string",
"enum": [
"prompt",
"static_text"
]
}
}
},
"TransferDestination": {
"oneOf": [
{
"$ref": "#/components/schemas/TransferDestinationPredefined"
},
{
"$ref": "#/components/schemas/TransferDestinationInferred"
}
]
},
"TransferDestinationPredefined": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"predefined"
]
},
"number": {
"type": "string",
"description": "E.164 number, internal extension, or dynamic variable such as `{{transfer_destination}}`.",
"example": "+18885551212"
},
"sip_uri": {
"type": "string",
"description": "SIP URI destination for SIP transfers.",
"example": "sip:support@pbx.example.com"
},
"extension": {
"type": "string",
"description": "DTMF extension to dial after the main transfer connects.",
"example": "1234"
}
}
},
"TransferDestinationInferred": {
"type": "object",
"required": [
"type",
"prompt"
],
"properties": {
"type": {
"type": "string",
"enum": [
"inferred"
]
},
"prompt": {
"type": "string",
"description": "Prompt used with the global prompt and transcript to infer the transfer destination.",
"example": "Transfer to billing at +18885550111 or sales at +18885550112 based on the user's request."
}
}
},
"TransferOption": {
"oneOf": [
{
"$ref": "#/components/schemas/TransferOptionColdTransfer"
},
{
"$ref": "#/components/schemas/TransferOptionWarmTransfer"
},
{
"$ref": "#/components/schemas/TransferOptionAgenticWarmTransfer"
}
]
},
"TransferOptionColdTransfer": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"cold_transfer"
]
},
"cold_transfer_mode": {
"type": "string",
"enum": [
"sip_invite",
"sip_refer"
],
"default": "sip_invite",
"description": "Use SIP INVITE for a new outbound leg, or SIP REFER to ask the carrier/PBX to transfer the call."
},
"show_transferee_as_caller": {
"type": "boolean",
"description": "Show the original caller as caller ID when supported. Applies to SIP INVITE transfers."
},
"transfer_ring_duration_ms": {
"type": "integer",
"minimum": 5000,
"maximum": 90000
}
}
},
"TransferOptionWarmTransfer": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"warm_transfer"
]
},
"show_transferee_as_caller": {
"type": "boolean"
},
"agent_detection_timeout_ms": {
"type": "integer",
"description": "Milliseconds to wait for human detection before treating the transfer as failed."
},
"transfer_ring_duration_ms": {
"type": "integer",
"minimum": 5000,
"maximum": 90000
},
"on_hold_music": {
"type": "string",
"enum": [
"none",
"relaxing_sound",
"uplifting_beats",
"ringtone"
]
},
"public_handoff_option": {
"$ref": "#/components/schemas/WarmTransferHandoffOption",
"nullable": true
},
"private_handoff_option": {
"$ref": "#/components/schemas/WarmTransferHandoffOption",
"nullable": true
},
"ivr_option": {
"$ref": "#/components/schemas/WarmTransferPrompt"
},
"opt_out_human_detection": {
"type": "boolean"
},
"enable_bridge_audio_cue": {
"type": "boolean",
"default": true
}
}
},
"WarmTransferHandoffOption": {
"oneOf": [
{
"$ref": "#/components/schemas/WarmTransferPrompt"
},
{
"$ref": "#/components/schemas/WarmTransferStaticMessage"
}
]
},
"WarmTransferPrompt": {
"type": "object",
"required": [
"type",
"prompt"
],
"properties": {
"type": {
"type": "string",
"enum": [
"prompt"
]
},
"prompt": {
"type": "string"
}
}
},
"WarmTransferStaticMessage": {
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"type": {
"type": "string",
"enum": [
"static_message"
]
},
"message": {
"type": "string"
}
}
},
"TransferOptionAgenticWarmTransfer": {
"type": "object",
"required": [
"type",
"agentic_transfer_config"
],
"properties": {
"type": {
"type": "string",
"enum": [
"agentic_warm_transfer"
]
},
"show_transferee_as_caller": {
"type": "boolean"
},
"on_hold_music": {
"type": "string",
"enum": [
"none",
"relaxing_sound",
"uplifting_beats",
"ringtone"
]
},
"transfer_ring_duration_ms": {
"type": "integer",
"minimum": 5000,
"maximum": 90000
},
"public_handoff_option": {
"$ref": "#/components/schemas/WarmTransferHandoffOption",
"nullable": true
},
"agentic_transfer_config": {
"type": "object",
"required": [
"transfer_agent"
],
"properties": {
"transfer_agent": {
"type": "object",
"required": [
"agent_id",
"agent_version"
],
"properties": {
"agent_id": {
"type": "string"
},
"agent_version": {
"type": "integer",
"default": 0
}
}
},
"transfer_timeout_ms": {
"type": "integer",
"default": 30000
},
"action_on_timeout": {
"type": "string",
"enum": [
"cancel_transfer",
"bridge_transfer"
],
"default": "cancel_transfer"
}
}
},
"enable_bridge_audio_cue": {
"type": "boolean",
"default": true
}
}
},
"EndCallTool": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"end_call"
]
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"speak_during_execution": {
"type": "boolean"
},
"execution_message_description": {
"type": "string"
},
"execution_message_type": {
"type": "string",
"enum": [
"prompt",
"static_text"
]
}
}
},
"BridgeTransferTool": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"bridge_transfer"
]
},
"name": {
"type": "string",
"default": "bridge_transfer"
},
"description": {
"type": "string"
}
}
},
"CancelTransferTool": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"cancel_transfer"
]
},
"name": {
"type": "string",
"default": "cancel_transfer"
},
"description": {
"type": "string"
}
}
},
"CustomFunctionTool": {
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"type": "string",
"enum": [
"function"
]
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"parameters": {
"type": "object",
"additionalProperties": true
}
}
},
"Tool": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"name",
"type"
]
},
"LlmState": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"state_prompt": {
"type": "string"
},
"edges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LlmStateEdge"
}
},
"tools": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LlmTool"
}
}
}
},
"LlmStateEdge": {
"type": "object",
"required": [
"destination_state_name",
"description"
],
"properties": {
"destination_state_name": {
"type": "string"
},
"description": {
"type": "string"
}
}
},
"McpConnection": {
"type": "object",
"required": [
"name",
"url"
],
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"headers": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"query_params": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"timeout_ms": {
"type": "integer"
}
}
},
"Llm": {
"allOf": [
{
"$ref": "#/components/schemas/LlmSummary"
},
{
"type": "object",
"additionalProperties": true,
"properties": {
"model": {
"type": "string"
},
"s2s_model": {
"type": "string",
"nullable": true
},
"general_prompt": {
"type": "string",
"nullable": true
},
"begin_message": {
"type": "string",
"nullable": true
},
"responsiveness": {
"type": "string",
"nullable": true
},
"general_tools": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LlmTool"
}
},
"states": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LlmState"
}
},
"starting_state": {
"type": "string",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
]
},
"UpdateLlmRequest": {
"type": "object",
"required": [
"workspaceId"
],
"additionalProperties": true,
"properties": {
"workspaceId": {
"type": "integer"
},
"general_prompt": {
"type": "string",
"nullable": true
},
"begin_message": {
"type": "string",
"nullable": true
},
"responsiveness": {
"type": "string"
},
"model": {
"type": "string"
},
"s2s_model": {
"type": "string",
"nullable": true,
"description": "Speech-to-speech model. Set either `model` or `s2s_model`, not both."
},
"start_speaker": {
"type": "string",
"enum": [
"user",
"agent"
]
},
"begin_after_user_silence_ms": {
"type": "integer",
"nullable": true
},
"model_temperature": {
"type": "number"
},
"model_high_priority": {
"type": "boolean"
},
"tool_call_strict_mode": {
"type": "boolean"
},
"knowledge_base_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"kb_config": {
"type": "object",
"additionalProperties": true
},
"general_tools": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LlmTool"
}
},
"states": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LlmState"
}
},
"starting_state": {
"type": "string",
"nullable": true
},
"default_dynamic_variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"mcps": {
"type": "array",
"items": {
"$ref": "#/components/schemas/McpConnection"
}
},
"version": {
"type": "integer",
"description": "Optional LLM version number when included in the update body. To target an existing version, use the `version` query parameter."
}
}
},
"AgentSummary": {
"type": "object",
"properties": {
"agent_id": {
"type": "string"
},
"agent_name": {
"type": "string"
},
"version": {
"type": "integer"
}
},
"required": [
"agent_id",
"version"
]
},
"CreateAgentRequest": {
"type": "object",
"additionalProperties": true,
"required": [
"workspaceId",
"agent_name",
"voice_id",
"response_engine"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"agent_name": {
"type": "string"
},
"voice_id": {
"type": "string"
},
"voice_model": {
"$ref": "#/components/schemas/VoiceModel"
},
"fallback_voice_ids": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"language": {
"type": "string",
"default": "en-US"
},
"response_engine": {
"$ref": "#/components/schemas/ResponseEngine"
},
"webhook_url": {
"type": "string",
"format": "uri",
"nullable": true
},
"webhook_events": {
"type": "array",
"items": {
"type": "string"
}
},
"webhook_timeout_ms": {
"type": "integer"
},
"response_threshold": {
"type": "number"
},
"interruption_sensitivity": {
"type": "number"
},
"ambient_sound": {
"type": "string"
},
"ambient_sound_volume": {
"type": "number"
},
"responsiveness": {
"type": "number"
},
"enable_dynamic_responsiveness": {
"type": "boolean"
},
"voice_temperature": {
"type": "number",
"minimum": 0,
"maximum": 2
},
"voice_speed": {
"type": "number",
"minimum": 0.5,
"maximum": 2
},
"enable_dynamic_voice_speed": {
"type": "boolean"
},
"volume": {
"type": "number",
"minimum": 0,
"maximum": 2
},
"voice_emotion": {
"type": "string",
"nullable": true
},
"enable_expressive_mode": {
"type": "boolean",
"description": "Enables expressive voice tags for supported voices."
},
"expressive_emotion_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"expressive_mode_prompt": {
"type": "string",
"nullable": true
},
"denoising_mode": {
"type": "string",
"enum": [
"noise-cancellation",
"noise-and-background-speech-cancellation"
]
},
"stt_mode": {
"type": "string",
"enum": [
"fast",
"accurate",
"custom"
]
},
"custom_stt_config": {
"$ref": "#/components/schemas/CustomSttConfig"
},
"vocab_specialization": {
"type": "string",
"enum": [
"general",
"medical"
]
},
"boosted_keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"handbook_config": {
"type": "object",
"additionalProperties": true
},
"max_call_duration_ms": {
"type": "integer"
},
"end_call_after_silence_ms": {
"type": "integer"
}
}
},
"VoiceModel": {
"type": "string",
"nullable": true,
"enum": [
"eleven_turbo_v2",
"eleven_flash_v2",
"eleven_turbo_v2_5",
"eleven_flash_v2_5",
"eleven_multilingual_v2",
"eleven_v3",
"sonic-3",
"sonic-3-latest",
"sonic-3.5",
"tts-1",
"gpt-4o-mini-tts",
"speech-02-turbo",
"speech-2.8-turbo",
"s1",
"s2-pro",
"s2.1-pro",
"auto",
null
],
"description": "Voice synthesis model for the selected voice. When omitted or set to auto for an ElevenLabs voice, new agents default to `eleven_turbo_v2`."
},
"ResponseEngine": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"llm_id": {
"type": "string"
}
},
"required": [
"type"
]
},
"CustomSttConfig": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"properties": {
"provider": {
"type": "string",
"enum": [
"deepgram",
"azure",
"soniox",
"assemblyai"
],
"description": "Realtime transcription provider used when stt_mode is custom."
},
"endpointing_ms": {
"type": "integer",
"minimum": 10,
"maximum": 3000,
"description": "Endpointing delay in milliseconds for the selected provider."
}
}
},
"Agent": {
"allOf": [
{
"$ref": "#/components/schemas/AgentSummary"
},
{
"type": "object",
"additionalProperties": true,
"properties": {
"voice_id": {
"type": "string"
},
"voice_model": {
"$ref": "#/components/schemas/VoiceModel"
},
"fallback_voice_ids": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"language": {
"type": "string",
"nullable": true
},
"response_engine": {
"$ref": "#/components/schemas/ResponseEngine"
},
"webhook_url": {
"type": "string",
"format": "uri",
"nullable": true
},
"webhook_events": {
"type": "array",
"items": {
"type": "string"
}
},
"webhook_timeout_ms": {
"type": "integer",
"nullable": true
},
"response_threshold": {
"type": "number",
"nullable": true
},
"interruption_sensitivity": {
"type": "number",
"nullable": true
},
"ambient_sound": {
"type": "string",
"nullable": true
},
"ambient_sound_volume": {
"type": "number",
"nullable": true
},
"responsiveness": {
"type": "number",
"nullable": true
},
"enable_dynamic_responsiveness": {
"type": "boolean",
"nullable": true
},
"voice_temperature": {
"type": "number",
"nullable": true
},
"voice_speed": {
"type": "number",
"nullable": true
},
"enable_dynamic_voice_speed": {
"type": "boolean",
"nullable": true
},
"volume": {
"type": "number",
"nullable": true
},
"voice_emotion": {
"type": "string",
"nullable": true
},
"enable_expressive_mode": {
"type": "boolean",
"nullable": true
},
"expressive_emotion_tags": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"expressive_mode_prompt": {
"type": "string",
"nullable": true
},
"denoising_mode": {
"type": "string",
"nullable": true
},
"stt_mode": {
"type": "string",
"nullable": true,
"enum": [
"fast",
"accurate",
"custom",
null
]
},
"custom_stt_config": {
"$ref": "#/components/schemas/CustomSttConfig"
},
"vocab_specialization": {
"type": "string",
"nullable": true
},
"boosted_keywords": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"handbook_config": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"max_call_duration_ms": {
"type": "integer",
"nullable": true
},
"end_call_after_silence_ms": {
"type": "integer",
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
]
},
"UpdateAgentRequest": {
"type": "object",
"additionalProperties": true,
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"agent_name": {
"type": "string"
},
"voice_id": {
"type": "string"
},
"voice_model": {
"$ref": "#/components/schemas/VoiceModel"
},
"fallback_voice_ids": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"language": {
"type": "string"
},
"response_engine": {
"$ref": "#/components/schemas/ResponseEngine"
},
"interruption_sensitivity": {
"type": "number"
},
"max_call_duration_ms": {
"type": "integer"
},
"responsiveness": {
"type": "number"
},
"enable_dynamic_responsiveness": {
"type": "boolean"
},
"voice_temperature": {
"type": "number",
"minimum": 0,
"maximum": 2
},
"voice_speed": {
"type": "number",
"minimum": 0.5,
"maximum": 2
},
"enable_dynamic_voice_speed": {
"type": "boolean"
},
"volume": {
"type": "number",
"minimum": 0,
"maximum": 2
},
"voice_emotion": {
"type": "string",
"nullable": true
},
"enable_expressive_mode": {
"type": "boolean"
},
"expressive_emotion_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"expressive_mode_prompt": {
"type": "string",
"nullable": true
},
"denoising_mode": {
"type": "string",
"enum": [
"noise-cancellation",
"noise-and-background-speech-cancellation"
]
},
"stt_mode": {
"type": "string",
"enum": [
"fast",
"accurate",
"custom"
]
},
"custom_stt_config": {
"$ref": "#/components/schemas/CustomSttConfig"
},
"vocab_specialization": {
"type": "string",
"enum": [
"general",
"medical"
]
},
"boosted_keywords": {
"type": "array",
"items": {
"type": "string"
}
},
"handbook_config": {
"type": "object",
"additionalProperties": true
},
"end_call_after_silence_ms": {
"type": "integer"
}
}
},
"AgentVersion": {
"type": "object",
"properties": {
"agent_id": {
"type": "string"
},
"version": {
"type": "integer"
},
"base_version": {
"type": "integer",
"nullable": true
},
"is_published": {
"type": "boolean"
},
"version_title": {
"type": "string",
"nullable": true
},
"version_description": {
"type": "string",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"agent_id",
"version"
]
},
"CreateAgentVersionRequest": {
"type": "object",
"required": [
"workspaceId",
"baseVersion"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"baseVersion": {
"type": "integer",
"minimum": 0,
"description": "Existing version used as the base for the new draft."
}
}
},
"PublishAgentVersionRequest": {
"type": "object",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"versionTitle": {
"type": "string",
"description": "Optional title stored on the published version."
},
"versionDescription": {
"type": "string",
"description": "Optional description stored on the published version."
}
}
},
"ChatAgentListResponse": {
"oneOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatAgentSummary"
}
},
{
"$ref": "#/components/schemas/ChatAgentListEnvelope"
}
]
},
"ChatAgentSummary": {
"allOf": [
{
"$ref": "#/components/schemas/ChatAgentVersion"
},
{
"type": "object",
"properties": {
"agent_name": {
"type": "string"
},
"response_engine": {
"$ref": "#/components/schemas/ChatResponseEngine"
},
"auto_close_message": {
"type": "string",
"nullable": true
},
"is_public": {
"type": "boolean",
"nullable": true
}
}
}
]
},
"ChatAgentVersion": {
"type": "object",
"properties": {
"agent_id": {
"type": "string"
},
"version": {
"type": "integer"
},
"base_version": {
"type": "integer",
"nullable": true
},
"is_published": {
"type": "boolean"
},
"version_title": {
"type": "string",
"nullable": true
},
"version_description": {
"type": "string",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"agent_id",
"version"
]
},
"ChatResponseEngine": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"uponai-llm",
"uponai-custom-llm"
]
},
"llm_id": {
"type": "string",
"nullable": true
}
},
"required": [
"type"
]
},
"ChatAgentListEnvelope": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatAgentSummary"
}
},
"pagination_key": {
"type": "string",
"nullable": true
},
"pagination_key_version": {
"type": "integer",
"nullable": true
}
}
},
"CreateChatAgentRequest": {
"type": "object",
"required": [
"workspaceId",
"agent_name",
"response_engine"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"agent_name": {
"type": "string"
},
"response_engine": {
"$ref": "#/components/schemas/ChatResponseEngine"
},
"auto_close_message": {
"type": "string",
"nullable": true
},
"end_chat_after_silence_ms": {
"type": "integer"
},
"timezone": {
"type": "string"
},
"webhook_url": {
"type": "string",
"format": "uri",
"nullable": true
},
"webhook_events": {
"type": "array",
"items": {
"type": "string"
}
},
"webhook_timeout_ms": {
"type": "integer"
},
"data_storage_setting": {
"type": "string",
"enum": [
"everything",
"everything_except_pii",
"basic_attributes_only"
]
},
"data_storage_retention_days": {
"type": "integer"
},
"post_chat_analysis_data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatAgentAnalysisField"
}
},
"post_chat_analysis_model": {
"type": "string"
},
"pii_config": {
"type": "object",
"additionalProperties": true
},
"guardrail_config": {
"type": "object",
"additionalProperties": true
},
"handbook_config": {
"type": "object",
"additionalProperties": true
},
"is_public": {
"type": "boolean"
},
"uponai_dynamic_variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"ChatAgentAnalysisField": {
"type": "object",
"properties": {
"type": {
"type": "string",
"example": "chat_summary"
},
"name": {
"type": "string",
"example": "summary"
},
"description": {
"type": "string",
"nullable": true,
"example": "Short summary of the completed chat."
},
"prompt": {
"type": "string",
"nullable": true
}
},
"required": [
"type",
"name"
]
},
"ChatAgent": {
"allOf": [
{
"$ref": "#/components/schemas/ChatAgentSummary"
},
{
"type": "object",
"properties": {
"end_chat_after_silence_ms": {
"type": "integer",
"nullable": true
},
"timezone": {
"type": "string",
"nullable": true
},
"webhook_url": {
"type": "string",
"format": "uri",
"nullable": true
},
"webhook_events": {
"type": "array",
"items": {
"type": "string"
}
},
"webhook_timeout_ms": {
"type": "integer",
"nullable": true
},
"data_storage_setting": {
"type": "string",
"enum": [
"everything",
"everything_except_pii",
"basic_attributes_only"
],
"nullable": true
},
"data_storage_retention_days": {
"type": "integer",
"nullable": true
},
"post_chat_analysis_data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatAgentAnalysisField"
}
},
"post_chat_analysis_model": {
"type": "string",
"nullable": true
},
"pii_config": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"guardrail_config": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"handbook_config": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"override_agent_id": {
"type": "string",
"nullable": true
},
"uponai_dynamic_variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"created_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updated_at": {
"type": "string",
"format": "date-time",
"nullable": true
}
}
}
]
},
"UpdateChatAgentRequest": {
"type": "object",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"agent_name": {
"type": "string"
},
"response_engine": {
"$ref": "#/components/schemas/ChatResponseEngine"
},
"auto_close_message": {
"type": "string",
"nullable": true
},
"end_chat_after_silence_ms": {
"type": "integer"
},
"timezone": {
"type": "string"
},
"webhook_url": {
"type": "string",
"format": "uri",
"nullable": true
},
"webhook_events": {
"type": "array",
"items": {
"type": "string"
}
},
"webhook_timeout_ms": {
"type": "integer"
},
"data_storage_setting": {
"type": "string",
"enum": [
"everything",
"everything_except_pii",
"basic_attributes_only"
]
},
"data_storage_retention_days": {
"type": "integer"
},
"post_chat_analysis_data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatAgentAnalysisField"
}
},
"post_chat_analysis_model": {
"type": "string"
},
"pii_config": {
"type": "object",
"additionalProperties": true
},
"guardrail_config": {
"type": "object",
"additionalProperties": true
},
"handbook_config": {
"type": "object",
"additionalProperties": true
},
"is_public": {
"type": "boolean"
},
"uponai_dynamic_variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"ChatAgentVersionListResponse": {
"oneOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatAgentVersion"
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatAgentVersion"
}
}
}
}
]
},
"ChatListResponse": {
"oneOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Chat"
}
},
{
"$ref": "#/components/schemas/ChatListEnvelope"
}
]
},
"Chat": {
"type": "object",
"properties": {
"chatId": {
"type": "string"
},
"agentId": {
"type": "string"
},
"version": {
"type": "integer",
"nullable": true
},
"status": {
"type": "string"
},
"type": {
"type": "string",
"nullable": true,
"example": "web_chat"
},
"metadata": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"customAttributes": {
"type": "object",
"additionalProperties": true
},
"startedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"endedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"transcript": {
"type": "string",
"nullable": true
},
"messages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatMessage"
}
},
"chatCost": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"chatAnalysis": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"collectedDynamicVariables": {
"type": "object",
"additionalProperties": true
},
"uponai_dynamic_variables": {
"type": "object",
"additionalProperties": true
},
"overrideDynamicVariables": {
"type": "object",
"nullable": true,
"additionalProperties": true
}
},
"required": [
"chatId",
"agentId",
"status",
"messages"
]
},
"ChatMessage": {
"type": "object",
"properties": {
"role": {
"type": "string",
"example": "assistant"
},
"content": {
"type": "string",
"nullable": true,
"example": "I can help with pricing and onboarding."
},
"name": {
"type": "string",
"nullable": true
},
"tool_calls": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"required": [
"role"
]
},
"ChatListEnvelope": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Chat"
}
},
"pagination_key": {
"type": "string",
"nullable": true
}
}
},
"CreateChatRequest": {
"type": "object",
"required": [
"workspaceId",
"agent_id"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"agent_id": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"uponai_dynamic_variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"CreateOutboundSmsChatRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CreateChatRequest"
},
{
"type": "object",
"required": [
"from_number",
"to_number"
],
"properties": {
"from_number": {
"type": "string",
"example": "+14155550100"
},
"to_number": {
"type": "string",
"example": "+14155550199"
}
}
}
]
},
"UpdateChatRequest": {
"type": "object",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"custom_attributes": {
"type": "object",
"additionalProperties": true
},
"override_dynamic_variables": {
"type": "object",
"additionalProperties": true
}
}
},
"CreateChatCompletionRequest": {
"type": "object",
"required": [
"workspaceId",
"content"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"content": {
"type": "string"
}
}
},
"ChatCompletionResponse": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChatMessage"
}
}
},
"required": [
"messages"
]
},
"ChatWidgetConfig": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"publicKey": {
"type": "string",
"description": "Public key used by the embeddable browser script.",
"example": "upon_widget_7d41a8d0c84f4d1fbf8ad4f1"
},
"workspaceId": {
"type": "integer"
},
"agentId": {
"type": "string",
"description": "Chat agent that powers this widget.",
"example": "chat_agent_01hzk4q6dr3n0d4qzpw9z6gth6"
},
"agentVersion": {
"type": "integer",
"nullable": true,
"description": "Optional fixed chat agent version. Null uses the latest published version."
},
"title": {
"type": "string",
"example": "How can we help?"
},
"logoUrl": {
"type": "string",
"nullable": true,
"format": "uri"
},
"themeColor": {
"type": "string",
"example": "#071a3e"
},
"componentColor": {
"type": "string",
"example": "#2563eb"
},
"fabText": {
"type": "string",
"example": "Need help?"
},
"botName": {
"type": "string",
"example": "Support"
},
"popupMessage": {
"type": "string",
"nullable": true,
"example": "Questions? We are here."
},
"showAiPopup": {
"type": "boolean"
},
"showAiPopupTime": {
"type": "integer",
"description": "Seconds to wait before showing the popup prompt."
},
"autoOpen": {
"type": "boolean"
},
"allowedOrigins": {
"type": "array",
"description": "Website origins allowed to load and use this widget. Empty allows any origin; use exact origins such as https://example.com for production embeds.\n",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"isEnabled": {
"type": "boolean"
},
"embedScript": {
"type": "string",
"description": "Complete script tag to paste into a website.",
"example": ""
}
},
"required": [
"id",
"publicKey",
"workspaceId",
"agentId",
"title",
"themeColor",
"componentColor",
"embedScript"
]
},
"CreateChatWidgetRequest": {
"type": "object",
"required": [
"workspaceId",
"agentId"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"agentId": {
"type": "string",
"description": "Chat agent that powers the widget."
},
"agentVersion": {
"type": "integer",
"nullable": true,
"minimum": 0
},
"title": {
"type": "string",
"default": "Chat"
},
"logoUrl": {
"type": "string",
"nullable": true,
"format": "uri"
},
"color": {
"type": "string",
"description": "Shorthand that sets both themeColor and componentColor when specific colors are omitted.",
"example": "#2563eb"
},
"themeColor": {
"type": "string",
"default": "#071a3e"
},
"componentColor": {
"type": "string",
"default": "#3E6AEF"
},
"fabText": {
"type": "string",
"default": "Need support?"
},
"botName": {
"type": "string",
"default": "AI Assistant"
},
"popupMessage": {
"type": "string",
"nullable": true
},
"showAiPopup": {
"type": "boolean",
"default": true
},
"showAiPopupTime": {
"type": "integer",
"default": 5,
"minimum": 0
},
"autoOpen": {
"type": "boolean",
"default": false
},
"allowedOrigins": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object",
"additionalProperties": true
}
}
},
"UpdateChatWidgetRequest": {
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "Chat agent that powers the widget."
},
"agentVersion": {
"type": "integer",
"nullable": true,
"minimum": 0
},
"title": {
"type": "string"
},
"logoUrl": {
"type": "string",
"nullable": true,
"format": "uri"
},
"color": {
"type": "string",
"description": "Shorthand that sets both themeColor and componentColor when specific colors are omitted."
},
"themeColor": {
"type": "string"
},
"componentColor": {
"type": "string"
},
"fabText": {
"type": "string"
},
"botName": {
"type": "string"
},
"popupMessage": {
"type": "string",
"nullable": true
},
"showAiPopup": {
"type": "boolean"
},
"showAiPopupTime": {
"type": "integer",
"minimum": 0
},
"autoOpen": {
"type": "boolean"
},
"allowedOrigins": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"isEnabled": {
"type": "boolean"
}
}
},
"ConversationFlowSummary": {
"type": "object",
"properties": {
"conversation_flow_id": {
"type": "string"
},
"version": {
"type": "integer"
},
"start_speaker": {
"type": "string",
"nullable": true
}
},
"required": [
"conversation_flow_id",
"version"
]
},
"CreateConversationFlowRequest": {
"type": "object",
"required": [
"workspaceId",
"start_speaker",
"nodes"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"global_prompt": {
"type": "string"
},
"start_speaker": {
"type": "string"
},
"model_choice": {
"$ref": "#/components/schemas/ModelChoice"
},
"nodes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConversationNode"
}
}
}
},
"ModelChoice": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"model": {
"type": "string"
}
},
"required": [
"type"
]
},
"ConversationNode": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"instruction": {
"$ref": "#/components/schemas/Instruction"
},
"edges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConversationEdge"
}
}
},
"required": [
"id",
"type"
]
},
"Instruction": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"text": {
"type": "string"
}
},
"required": [
"type"
]
},
"ConversationEdge": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"transition_condition": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"prompt": {
"type": "string"
}
},
"required": [
"type"
]
},
"destination_node_id": {
"type": "string"
}
},
"required": [
"id",
"transition_condition",
"destination_node_id"
]
},
"ConversationFlow": {
"allOf": [
{
"$ref": "#/components/schemas/ConversationFlowSummary"
},
{
"type": "object",
"properties": {
"workspaceId": {
"type": "integer",
"nullable": true
},
"global_prompt": {
"type": "string",
"nullable": true
},
"start_speaker": {
"type": "string",
"nullable": true
},
"model_choice": {
"$ref": "#/components/schemas/ModelChoice"
},
"nodes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConversationNode"
}
}
}
}
]
},
"UpdateConversationFlowRequest": {
"type": "object",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"global_prompt": {
"type": "string"
},
"model_choice": {
"$ref": "#/components/schemas/ModelChoice"
},
"nodes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConversationNode"
}
}
}
},
"KnowledgeBaseSummary": {
"type": "object",
"properties": {
"knowledgeBaseId": {
"type": "string",
"example": "knowledge_base_17c5db1600cea2b4"
},
"name": {
"type": "string",
"example": "Customer Support FAQ"
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"ready",
"failed"
],
"example": "processing"
}
},
"required": [
"knowledgeBaseId",
"name",
"status"
]
},
"CreateKnowledgeBaseRequest": {
"type": "object",
"required": [
"workspaceId",
"name"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"name": {
"type": "string"
},
"description": {
"type": "string",
"example": "Grounding material for customer support."
},
"enableAutoRefresh": {
"type": "boolean",
"description": "Automatically refresh URL-based sources on the provider cadence.",
"example": false
},
"maxChunkSize": {
"type": "integer",
"minimum": 600,
"maximum": 6000,
"example": 2000
},
"minChunkSize": {
"type": "integer",
"minimum": 200,
"maximum": 2000,
"example": 400
},
"sources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KnowledgeBaseSourceInput"
}
}
}
},
"KnowledgeBaseSourceInput": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"text",
"url",
"document"
]
},
"text": {
"type": "string",
"example": "We issue refunds within 30 days of purchase."
},
"title": {
"type": "string",
"description": "Optional display title for text sources. If omitted, one is generated automatically.",
"example": "Refund Policy"
},
"url": {
"type": "string",
"format": "uri",
"example": "https://example.com/help/refunds"
},
"filename": {
"type": "string",
"example": "handbook.pdf"
},
"contentType": {
"type": "string",
"example": "application/pdf"
},
"base64": {
"type": "string",
"description": "Base64-encoded file contents for document sources.",
"example": "JVBERi0xLjQKJcfs..."
}
},
"required": [
"type"
]
},
"KnowledgeBase": {
"allOf": [
{
"$ref": "#/components/schemas/KnowledgeBaseSummary"
},
{
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true,
"example": "Grounding material for support agents."
},
"sources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KnowledgeBaseSource"
}
},
"workspaceId": {
"type": "integer",
"nullable": true,
"example": 58
},
"enableAutoRefresh": {
"type": "boolean",
"example": false
},
"lastRefreshedTimestamp": {
"type": "integer",
"nullable": true,
"example": 1773937556128
},
"maxChunkSize": {
"type": "integer",
"nullable": true,
"example": 2000
},
"minChunkSize": {
"type": "integer",
"nullable": true,
"example": 400
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-03-19T13:25:56.128Z"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-03-19T13:26:12.512Z"
}
}
}
]
},
"KnowledgeBaseSource": {
"oneOf": [
{
"$ref": "#/components/schemas/KnowledgeBaseSourceDocument"
},
{
"$ref": "#/components/schemas/KnowledgeBaseSourceText"
},
{
"$ref": "#/components/schemas/KnowledgeBaseSourceUrl"
}
]
},
"KnowledgeBaseSourceDocument": {
"type": "object",
"properties": {
"source_id": {
"type": "string",
"example": "kb_source_35e085a611328bd3"
},
"type": {
"type": "string",
"enum": [
"document"
],
"example": "document"
},
"filename": {
"type": "string",
"nullable": true,
"example": "benefits-guide.pdf"
},
"file_url": {
"type": "string",
"nullable": true,
"example": "https://cdn.example.com/knowledge-bases/benefits-guide.pdf"
},
"file_size": {
"type": "integer",
"nullable": true,
"example": 482311
}
},
"required": [
"source_id",
"type"
]
},
"KnowledgeBaseSourceText": {
"type": "object",
"properties": {
"source_id": {
"type": "string",
"example": "kb_source_41f4dfd2f142bf07"
},
"type": {
"type": "string",
"enum": [
"text"
],
"example": "text"
},
"title": {
"type": "string",
"nullable": true,
"example": "Refund Policy"
},
"content_url": {
"type": "string",
"nullable": true,
"example": "https://cdn.example.com/knowledge-bases/refund-policy.txt"
}
},
"required": [
"source_id",
"type"
]
},
"KnowledgeBaseSourceUrl": {
"type": "object",
"properties": {
"source_id": {
"type": "string",
"example": "kb_source_803751f5c87eab66"
},
"type": {
"type": "string",
"enum": [
"url"
],
"example": "url"
},
"url": {
"type": "string",
"format": "uri",
"example": "https://metro-ride.com/careers/"
}
},
"required": [
"source_id",
"type"
]
},
"AddKnowledgeBaseSourcesRequest": {
"type": "object",
"required": [
"workspaceId",
"sources"
],
"properties": {
"workspaceId": {
"type": "integer",
"example": 58
},
"sources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KnowledgeBaseSourceInput"
}
}
}
},
"Voice": {
"type": "object",
"properties": {
"voiceId": {
"type": "string"
},
"name": {
"type": "string"
},
"gender": {
"type": "string"
},
"language": {
"type": "string"
},
"accent": {
"type": "string"
},
"description": {
"type": "string"
},
"provider": {
"type": "string",
"nullable": true
},
"previewUrl": {
"type": "string",
"format": "uri"
},
"playbackOverrideUrl": {
"type": "string",
"format": "uri",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"voiceId",
"name"
]
},
"SearchCommunityVoiceRequest": {
"type": "object",
"required": [
"workspaceId",
"searchQuery"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"voiceProvider": {
"type": "string",
"enum": [
"elevenlabs",
"cartesia",
"minimax"
]
},
"searchQuery": {
"type": "string"
}
}
},
"SearchCommunityVoiceResponse": {
"type": "object",
"properties": {
"voices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchCommunityVoiceItem"
}
}
},
"required": [
"voices"
]
},
"SearchCommunityVoiceItem": {
"type": "object",
"properties": {
"providerVoiceId": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"publicUserId": {
"type": "string",
"nullable": true
},
"voiceProvider": {
"type": "string",
"enum": [
"elevenlabs",
"cartesia",
"minimax"
],
"nullable": true
}
}
},
"AddCommunityVoiceRequest": {
"type": "object",
"required": [
"workspaceId",
"providerVoiceId",
"voiceName"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"voiceProvider": {
"type": "string",
"enum": [
"elevenlabs",
"cartesia",
"minimax"
],
"default": "elevenlabs"
},
"providerVoiceId": {
"type": "string"
},
"voiceName": {
"type": "string"
},
"publicUserId": {
"type": "string",
"nullable": true
}
}
},
"CloneVoiceRequest": {
"type": "object",
"required": [
"workspaceId",
"voiceName",
"files"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"voiceProvider": {
"type": "string",
"enum": [
"elevenlabs",
"cartesia",
"minimax"
],
"default": "elevenlabs"
},
"voiceName": {
"type": "string"
},
"files": {
"type": "array",
"items": {
"type": "string",
"format": "binary"
}
}
}
},
"TestCaseDefinition": {
"allOf": [
{
"$ref": "#/components/schemas/TestCaseDefinitionInput"
},
{
"type": "object",
"properties": {
"test_case_definition_id": {
"type": "string"
},
"type": {
"type": "string"
},
"creation_timestamp": {
"type": "integer"
},
"user_modified_timestamp": {
"type": "integer"
}
},
"required": [
"test_case_definition_id"
]
}
]
},
"TestCaseDefinitionInput": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"response_engine": {
"$ref": "#/components/schemas/TestResponseEngine"
},
"user_prompt": {
"type": "string"
},
"metrics": {
"type": "array",
"items": {
"type": "string"
}
},
"dynamic_variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"tool_mocks": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"llm_model": {
"type": "string",
"nullable": true
}
}
},
"TestResponseEngine": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"llm",
"conversation-flow"
]
},
"llm_id": {
"type": "string",
"nullable": true
},
"conversation_flow_id": {
"type": "string",
"nullable": true
},
"version": {
"type": "integer",
"nullable": true
}
},
"required": [
"type"
]
},
"CreateTestCaseDefinitionRequest": {
"allOf": [
{
"$ref": "#/components/schemas/TestCaseDefinitionInput"
},
{
"type": "object",
"required": [
"workspaceId",
"name",
"response_engine",
"user_prompt",
"metrics"
],
"properties": {
"workspaceId": {
"type": "integer"
}
}
}
]
},
"BatchTest": {
"type": "object",
"properties": {
"test_case_batch_job_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"in_progress",
"complete"
]
},
"response_engine": {
"$ref": "#/components/schemas/TestResponseEngine"
},
"pass_count": {
"type": "integer",
"minimum": 0
},
"fail_count": {
"type": "integer",
"minimum": 0
},
"error_count": {
"type": "integer",
"minimum": 0
},
"total_count": {
"type": "integer",
"minimum": 0
},
"creation_timestamp": {
"type": "integer"
},
"user_modified_timestamp": {
"type": "integer"
}
},
"required": [
"test_case_batch_job_id",
"status"
]
},
"CreateBatchTestRequest": {
"type": "object",
"required": [
"workspaceId",
"response_engine",
"test_case_definition_ids"
],
"properties": {
"workspaceId": {
"type": "integer"
},
"response_engine": {
"$ref": "#/components/schemas/TestResponseEngine"
},
"test_case_definition_ids": {
"type": "array",
"minItems": 1,
"maxItems": 1000,
"items": {
"type": "string"
}
}
}
},
"UpdateTestCaseDefinitionRequest": {
"allOf": [
{
"$ref": "#/components/schemas/TestCaseDefinitionInput"
},
{
"type": "object",
"required": [
"workspaceId"
],
"properties": {
"workspaceId": {
"type": "integer"
}
}
}
]
},
"TestRun": {
"type": "object",
"properties": {
"test_case_job_id": {
"type": "string"
},
"status": {
"type": "string"
},
"test_case_definition_id": {
"type": "string"
},
"test_case_definition_snapshot": {
"$ref": "#/components/schemas/TestCaseDefinition"
},
"transcript_snapshot": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"result_explanation": {
"type": "string",
"nullable": true
},
"creation_timestamp": {
"type": "integer"
},
"user_modified_timestamp": {
"type": "integer"
}
},
"required": [
"test_case_job_id",
"status"
]
},
"Concurrency": {
"type": "object",
"properties": {
"maxConcurrent": {
"type": "integer"
},
"currentUsage": {
"type": "integer"
},
"purchasedConcurrency": {
"type": "integer"
},
"concurrencyPurchaseLimit": {
"type": "integer"
}
},
"required": [
"maxConcurrent",
"currentUsage"
]
},
"WorkspaceSummary": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"accountSid": {
"type": "string",
"nullable": true
},
"accountPath": {
"type": "string",
"nullable": true
},
"nativeTransferEnabled": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"nativeTransferEnabled"
]
},
"CreatePhoneCallRequest": {
"type": "object",
"additionalProperties": false,
"description": "Unknown top-level fields return HTTP 400 before a call is created. Supply dynamic variables using the documented field, with string values only.",
"required": [
"agentId",
"fromNumber",
"toNumber"
],
"properties": {
"agentId": {
"type": "string",
"description": "Unique agent identifier. The owning workspace is inferred from this value."
},
"workspaceId": {
"type": "integer",
"description": "Optional backward-compatible workspace hint. If supplied, it must match the workspace that owns agentId."
},
"fromNumber": {
"type": "string",
"description": "Caller identifier. For native-transfer workspaces this may be an imported number, extension, or platform-side pseudo DID when ignoreE164Validation is enabled."
},
"toNumber": {
"type": "string",
"description": "Destination identifier to dial. Standard phone calls should use E.164; native-transfer workspaces can also use configured extensions or pseudo numbers when ignoreE164Validation is enabled."
},
"customerName": {
"type": "string"
},
"carrierName": {
"type": "string"
},
"trunkName": {
"type": "string"
},
"overrideCid": {
"type": "string",
"description": "Optional SIP From display-name override. The selected fromNumber remains the actual caller ID/user part for native-transfer calls."
},
"callerIdFormat": {
"type": "string",
"enum": [
"10-digit",
"11-digit",
"e164"
],
"description": "Native-transfer only. Format applied to the caller ID before the outbound leg is dialed."
},
"toNumberFormat": {
"type": "string",
"enum": [
"10-digit",
"11-digit",
"e164"
],
"description": "Native-transfer only. Format applied to the destination number before the outbound leg is dialed."
},
"overrideAgentVersion": {
"type": "integer",
"minimum": 0,
"description": "Native-transfer only. Overrides the agent version for this specific call."
},
"agentOverride": {
"$ref": "#/components/schemas/CallAgentOverrideRequest"
},
"customFromNumber": {
"type": "string",
"description": "Optional custom caller identifier used when fromNumber is set to custom. This may be a configured non-E.164 identifier on supported trunk-based workspaces."
},
"customStatusHookUrl": {
"type": "string",
"format": "uri",
"description": "Per-call destination for branded call_started, call_ended, and call_analyzed events."
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"customSipHeaders": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Native-transfer only. Additional SIP headers merged into the outbound call request."
},
"ignoreE164Validation": {
"type": "boolean",
"description": "Native-transfer only. Disables E.164 validation so imported pseudo DIDs, extensions, and other custom telephony identifiers can be used. The platform may also enable this automatically when needed on supported workspaces."
},
"uponai_dynamic_variables": {
"description": "Dynamic variables with string values only (including empty strings). CamelCase variable containers are not supported.",
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"override_agent_version": {
"type": "integer",
"minimum": 0,
"description": "Alias for overrideAgentVersion."
},
"agent_override": {
"$ref": "#/components/schemas/CallAgentOverrideRequest"
},
"custom_sip_headers": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Alias for customSipHeaders."
},
"ignore_e164_validation": {
"type": "boolean",
"description": "Alias for ignoreE164Validation."
}
}
},
"CallAgentOverrideRequest": {
"type": "object",
"properties": {
"agent": {
"$ref": "#/components/schemas/CallAgentConfigOverride"
},
"llm": {
"$ref": "#/components/schemas/CallLlmOverride"
},
"conversationFlow": {
"$ref": "#/components/schemas/CallConversationFlowOverride"
}
}
},
"CallAgentConfigOverride": {
"type": "object",
"properties": {
"agentName": {
"type": "string"
},
"versionDescription": {
"type": "string"
},
"voiceId": {
"type": "string"
},
"responseEngine": {
"type": "object",
"additionalProperties": true
},
"responseThreshold": {
"type": "number"
},
"interruptionSensitivity": {
"type": "string"
},
"ambientSound": {
"type": "string"
},
"responsiveness": {
"type": "string"
},
"maxCallDurationMs": {
"type": "integer"
},
"beginMessageDelayMs": {
"type": "integer"
}
},
"additionalProperties": true
},
"CallLlmOverride": {
"type": "object",
"properties": {
"model": {
"type": "string"
},
"s2sModel": {
"type": "string"
},
"modelTemperature": {
"type": "number"
},
"modelHighPriority": {
"type": "boolean"
},
"toolCallStrictMode": {
"type": "boolean"
},
"knowledgeBaseIds": {
"type": "array",
"items": {
"type": "string"
}
},
"kbConfig": {
"type": "object",
"additionalProperties": true
},
"startSpeaker": {
"type": "string",
"enum": [
"user",
"agent"
]
},
"beginAfterUserSilenceMs": {
"type": "integer"
},
"beginMessage": {
"type": "string"
}
},
"additionalProperties": true
},
"CallConversationFlowOverride": {
"type": "object",
"properties": {
"modelChoice": {
"$ref": "#/components/schemas/ModelChoice"
},
"modelTemperature": {
"type": "number"
},
"toolCallStrictMode": {
"type": "boolean"
},
"knowledgeBaseIds": {
"type": "array",
"items": {
"type": "string"
}
},
"kbConfig": {
"type": "object",
"additionalProperties": true
},
"startSpeaker": {
"type": "string",
"enum": [
"user",
"agent"
]
},
"beginAfterUserSilenceMs": {
"type": "integer"
}
},
"additionalProperties": true
},
"CreatePhoneCallResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"call_sid": {
"type": "string"
},
"call": {
"$ref": "#/components/schemas/CallDetail"
}
}
},
"CallDetail": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"call": {
"$ref": "#/components/schemas/CallRecord"
}
},
"additionalProperties": true
},
"CallRecord": {
"type": "object",
"properties": {
"callId": {
"type": "string"
},
"callType": {
"type": "string"
},
"status": {
"type": "string"
},
"agentId": {
"type": "string"
},
"agentVersion": {
"type": "integer"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"optOutSensitiveDataStorage": {
"type": "boolean"
},
"accessToken": {
"type": "string",
"nullable": true
},
"expiresAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"webCallUrl": {
"type": "string",
"format": "uri",
"nullable": true
},
"uponai_dynamic_variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"CreateWebCallRequest": {
"type": "object",
"required": [
"agentId"
],
"properties": {
"workspaceId": {
"type": "integer",
"description": "Optional backward-compatible workspace hint. If supplied, it must match the workspace that owns agentId."
},
"agentId": {
"type": "string",
"description": "Unique agent identifier. The owning workspace is inferred from this value."
},
"agentVersion": {
"type": "integer"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"uponai_dynamic_variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"WebCall": {
"type": "object",
"properties": {
"callId": {
"type": "string"
},
"callType": {
"type": "string"
},
"status": {
"type": "string"
},
"agentId": {
"type": "string"
},
"agentVersion": {
"type": "integer"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"optOutSensitiveDataStorage": {
"type": "boolean"
},
"accessToken": {
"type": "string",
"nullable": true
},
"expiresAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"webCallUrl": {
"type": "string",
"format": "uri",
"nullable": true
},
"uponai_dynamic_variables": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"callId",
"status"
]
},
"CallList": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CallRecord"
}
},
"total": {
"type": "integer"
},
"pages": {
"type": "integer"
},
"currentPage": {
"type": "integer"
}
},
"required": [
"success",
"calls"
]
},
"V3ListCallsRequest": {
"type": "object",
"properties": {
"workspaceId": {
"type": "integer",
"description": "Optional branded extension to scope results to one accessible workspace."
},
"filter_criteria": {
"$ref": "#/components/schemas/CallFilter"
},
"sort_order": {
"type": "string",
"enum": [
"ascending",
"descending"
],
"default": "descending",
"description": "Sort calls by start timestamp."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 50,
"description": "Maximum number of calls to return."
},
"skip": {
"type": "integer",
"minimum": 0,
"default": 0,
"description": "Number of records to skip for pagination."
},
"pagination_key": {
"type": "string",
"description": "Pagination key from the previous response."
},
"include_total": {
"type": "boolean",
"default": false,
"description": "Whether to include the total count of matching calls."
}
}
},
"CallFilter": {
"type": "object",
"description": "Filter criteria for calls. All provided conditions are combined with AND.",
"properties": {
"agent": {
"type": "array",
"description": "Agent filters are combined with OR.",
"items": {
"$ref": "#/components/schemas/AgentFilter"
}
},
"call_id": {
"oneOf": [
{
"$ref": "#/components/schemas/StringFilter"
},
{
"$ref": "#/components/schemas/EnumFilter"
}
]
},
"batch_call_id": {
"$ref": "#/components/schemas/StringFilter"
},
"call_status": {
"$ref": "#/components/schemas/EnumFilter"
},
"in_voicemail": {
"$ref": "#/components/schemas/BooleanFilter"
},
"disconnection_reason": {
"$ref": "#/components/schemas/EnumFilter"
},
"from_number": {
"$ref": "#/components/schemas/StringFilter"
},
"to_number": {
"$ref": "#/components/schemas/StringFilter"
},
"call_type": {
"$ref": "#/components/schemas/EnumFilter"
},
"direction": {
"$ref": "#/components/schemas/EnumFilter"
},
"user_sentiment": {
"$ref": "#/components/schemas/EnumFilter"
},
"data_storage_setting": {
"$ref": "#/components/schemas/EnumFilter"
},
"call_successful": {
"$ref": "#/components/schemas/BooleanFilter"
},
"start_timestamp": {
"oneOf": [
{
"$ref": "#/components/schemas/NumberFilter"
},
{
"$ref": "#/components/schemas/RangeFilter"
}
]
},
"end_timestamp": {
"oneOf": [
{
"$ref": "#/components/schemas/NumberFilter"
},
{
"$ref": "#/components/schemas/RangeFilter"
}
]
},
"duration_ms": {
"oneOf": [
{
"$ref": "#/components/schemas/NumberFilter"
},
{
"$ref": "#/components/schemas/RangeFilter"
}
]
},
"combined_cost": {
"oneOf": [
{
"$ref": "#/components/schemas/NumberFilter"
},
{
"$ref": "#/components/schemas/RangeFilter"
}
]
}
}
},
"AgentFilter": {
"type": "object",
"required": [
"agent_id"
],
"properties": {
"agent_id": {
"type": "string",
"minLength": 1
},
"version": {
"type": "array",
"items": {
"type": "number"
}
}
}
},
"StringFilter": {
"type": "object",
"required": [
"type",
"op",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"string"
]
},
"op": {
"type": "string",
"enum": [
"eq",
"ne",
"sw",
"ew",
"co"
],
"description": "Equal, not equal, starts with, ends with, or contains."
},
"value": {
"type": "string"
}
}
},
"EnumFilter": {
"type": "object",
"required": [
"type",
"op",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"enum"
]
},
"op": {
"type": "string",
"enum": [
"in"
]
},
"value": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"BooleanFilter": {
"type": "object",
"required": [
"type",
"op",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"boolean"
]
},
"op": {
"type": "string",
"enum": [
"eq"
]
},
"value": {
"type": "boolean"
}
}
},
"NumberFilter": {
"type": "object",
"required": [
"type",
"op",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"number"
]
},
"op": {
"type": "string",
"enum": [
"eq",
"ne",
"gt",
"ge",
"lt",
"le"
]
},
"value": {
"type": "number"
}
}
},
"RangeFilter": {
"type": "object",
"required": [
"type",
"op",
"value"
],
"properties": {
"type": {
"type": "string",
"enum": [
"range"
]
},
"op": {
"type": "string",
"enum": [
"bt"
]
},
"value": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number"
}
}
}
},
"V3ListCallsResponse": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/V3CallResponse"
}
},
"pagination_key": {
"type": "string",
"nullable": true,
"description": "Pagination key for the next page, or null when no more results are available."
},
"has_more": {
"type": "boolean",
"description": "Whether more results are available."
},
"total": {
"type": "integer",
"description": "Total number of matching calls. Present only when include_total is true."
}
},
"required": [
"items",
"pagination_key",
"has_more"
]
},
"V3CallResponse": {
"oneOf": [
{
"$ref": "#/components/schemas/V3WebCallResponse"
},
{
"$ref": "#/components/schemas/V3PhoneCallResponse"
}
]
},
"V3WebCallResponse": {
"allOf": [
{
"$ref": "#/components/schemas/V3CallBase"
},
{
"type": "object",
"properties": {
"call_type": {
"type": "string",
"enum": [
"web_call"
]
},
"access_token": {
"type": "string",
"nullable": true
}
}
}
]
},
"V3CallBase": {
"type": "object",
"properties": {
"call_id": {
"type": "string"
},
"agent_id": {
"type": "string"
},
"agent_name": {
"type": "string",
"nullable": true
},
"agent_version": {
"type": "integer",
"nullable": true
},
"call_status": {
"type": "string",
"nullable": true
},
"start_timestamp": {
"type": "integer",
"nullable": true,
"description": "Start timestamp in milliseconds since epoch."
},
"end_timestamp": {
"type": "integer",
"nullable": true,
"description": "End timestamp in milliseconds since epoch."
},
"duration_ms": {
"type": "integer",
"nullable": true
},
"disconnection_reason": {
"type": "string",
"nullable": true
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"transcript": {
"type": "string",
"nullable": true
},
"transcript_object": {
"type": "object",
"additionalProperties": true,
"nullable": true
},
"transcript_with_tool_calls": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"nullable": true
},
"recording_url": {
"type": "string",
"format": "uri",
"nullable": true
},
"public_log_url": {
"type": "string",
"format": "uri",
"nullable": true
},
"call_analysis": {
"type": "object",
"additionalProperties": true
},
"call_cost": {
"type": "object",
"additionalProperties": true
},
"data_storage_setting": {
"type": "string",
"enum": [
"everything",
"everything_except_pii",
"basic_attributes_only"
],
"nullable": true
}
}
},
"V3PhoneCallResponse": {
"allOf": [
{
"$ref": "#/components/schemas/V3CallBase"
},
{
"type": "object",
"properties": {
"call_type": {
"type": "string",
"enum": [
"phone_call"
]
},
"from_number": {
"type": "string",
"nullable": true
},
"to_number": {
"type": "string",
"nullable": true
},
"direction": {
"type": "string",
"nullable": true
}
}
}
]
},
"CallHistoryList": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CallHistoryRecord"
}
},
"pagination": {
"type": "object",
"properties": {
"page": {
"type": "integer"
},
"limit": {
"type": "integer"
},
"total": {
"type": "integer"
},
"pages": {
"type": "integer"
}
}
},
"filters": {
"$ref": "#/components/schemas/CallHistoryFilters"
}
},
"required": [
"success",
"calls",
"pagination",
"filters"
]
},
"CallHistoryRecord": {
"type": "object",
"properties": {
"callSid": {
"type": "string"
},
"callStatus": {
"type": "string",
"nullable": true
},
"agentId": {
"type": "string",
"nullable": true
},
"agentVersion": {
"type": "integer",
"nullable": true
},
"agentName": {
"type": "string",
"nullable": true
},
"workspaceId": {
"type": "integer"
},
"workspaceName": {
"type": "string",
"nullable": true
},
"fromNumber": {
"type": "string",
"nullable": true
},
"toNumber": {
"type": "string",
"nullable": true
},
"direction": {
"type": "string",
"nullable": true
},
"customerName": {
"type": "string",
"nullable": true
},
"duration": {
"type": "integer",
"nullable": true
},
"startedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"createdAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"updatedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"recordingUrl": {
"type": "string",
"format": "uri",
"nullable": true
},
"sentiment": {
"type": "string",
"nullable": true
},
"summary": {
"type": "string",
"nullable": true
},
"voiceModel": {
"type": "string",
"nullable": true
},
"llmModel": {
"type": "string",
"nullable": true
},
"telecommunicationsProvider": {
"type": "string",
"nullable": true
},
"carrierSid": {
"type": "string",
"nullable": true
},
"carrierName": {
"type": "string",
"nullable": true
},
"archived": {
"type": "boolean"
},
"costs": {
"$ref": "#/components/schemas/CallHistoryCosts"
}
},
"required": [
"callSid",
"workspaceId",
"archived"
]
},
"CallHistoryCosts": {
"type": "object",
"properties": {
"voice": {
"type": "number",
"nullable": true
},
"llm": {
"type": "number",
"nullable": true
},
"voiceMarkup": {
"type": "number",
"nullable": true
},
"llmMarkup": {
"type": "number",
"nullable": true
},
"gross": {
"type": "number",
"nullable": true
},
"markup": {
"type": "number",
"nullable": true
},
"total": {
"type": "number",
"nullable": true
},
"markupRate": {
"type": "number",
"nullable": true
}
}
},
"CallHistoryFilters": {
"type": "object",
"properties": {
"workspaceId": {
"type": "integer"
},
"agentId": {
"type": "string",
"nullable": true
},
"agentVersion": {
"type": "integer",
"nullable": true
},
"status": {
"type": "string",
"nullable": true
},
"fromDate": {
"type": "string",
"format": "date-time",
"nullable": true
},
"toDate": {
"type": "string",
"format": "date-time",
"nullable": true
},
"search": {
"type": "string",
"nullable": true
},
"includeArchived": {
"type": "boolean"
},
"includeChildCalls": {
"type": "boolean"
}
}
},
"UpdateCallRequest": {
"type": "object",
"properties": {
"workspaceId": {
"type": "integer",
"description": "Optional backward-compatible fallback. Required only when the call cannot be resolved from stored call data."
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"optOutSensitiveDataStorage": {
"type": "boolean"
}
}
},
"CallActionWorkspaceRequest": {
"type": "object",
"properties": {
"workspaceId": {
"type": "integer",
"description": "Optional backward-compatible fallback. Required only when the call cannot be resolved from stored call data."
}
}
},
"EndLiveCallResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"callId": {
"type": "string"
},
"status": {
"type": "string",
"example": "ended"
},
"call": {
"$ref": "#/components/schemas/CallRecord",
"nullable": true
}
},
"required": [
"success",
"callId",
"status"
]
},
"UpdateLiveCallRequest": {
"allOf": [
{
"$ref": "#/components/schemas/CallActionWorkspaceRequest"
},
{
"type": "object",
"properties": {
"fieldsToOverride": {
"$ref": "#/components/schemas/UpdateLiveCallFields"
},
"fields_to_override": {
"$ref": "#/components/schemas/UpdateLiveCallFields"
},
"callControl": {
"$ref": "#/components/schemas/LiveCallControl"
},
"call_control": {
"$ref": "#/components/schemas/LiveCallControl"
},
"listen": {
"$ref": "#/components/schemas/LiveCallListenControl"
}
}
}
]
},
"UpdateLiveCallFields": {
"type": "object",
"properties": {
"dynamicVariables": {
"type": "object",
"nullable": true,
"additionalProperties": {
"type": "string"
},
"description": "Delta of dynamic variable overrides. Set to null to remove existing overrides."
},
"override_dynamic_variables": {
"type": "object",
"nullable": true,
"additionalProperties": {
"type": "string"
},
"description": "Snake_case alias for dynamicVariables."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Metadata persisted to the call record. Maximum size is 50KB."
},
"dataStorageSetting": {
"type": "string",
"enum": [
"everything",
"everything_except_pii",
"basic_attributes_only"
],
"description": "Data storage setting for this call. More restrictive settings may not be relaxed during a live call."
},
"data_storage_setting": {
"type": "string",
"enum": [
"everything",
"everything_except_pii",
"basic_attributes_only"
],
"description": "Snake_case alias for dataStorageSetting."
}
}
},
"LiveCallControl": {
"type": "object",
"properties": {
"triggerResponse": {
"type": "boolean",
"description": "When true, requests that the live agent generate a response when appropriate. If the agent is speaking, the current response may be interrupted depending on the agent interruption settings. If the user is speaking, the request is ignored so the agent does not talk over them.\n"
},
"trigger_response": {
"type": "boolean",
"description": "Snake_case alias for triggerResponse."
},
"additionalContext": {
"type": "string",
"minLength": 1,
"description": "Non-empty text injected into the live call context for the next agent response."
},
"additional_context": {
"type": "string",
"minLength": 1,
"description": "Snake_case alias for additionalContext."
},
"listen": {
"$ref": "#/components/schemas/LiveCallListenControl"
}
}
},
"LiveCallListenControl": {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"start",
"stop"
],
"description": "Start or stop a listen-only audio stream for the live call."
},
"url": {
"type": "string",
"format": "uri",
"description": "WebSocket URL that will receive the live call audio stream. Required when action is start."
},
"mixType": {
"type": "string",
"enum": [
"mono",
"mixed",
"stereo"
],
"default": "mixed",
"description": "Audio channel mix for the stream."
},
"sampleRate": {
"type": "integer",
"enum": [
8000,
16000,
24000,
48000
],
"default": 8000,
"description": "Sample rate for the stream."
},
"disableBidirectionalAudio": {
"type": "boolean",
"default": true,
"description": "Keep the stream listen-only."
},
"wsAuth": {
"type": "object",
"additionalProperties": true,
"description": "Optional WebSocket authentication payload."
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Optional metadata delivered with the stream setup."
}
},
"required": [
"action"
]
},
"UpdateLiveCallResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"callId": {
"type": "string"
},
"result": {
"type": "object",
"additionalProperties": true
},
"listen": {
"type": "object",
"additionalProperties": true,
"nullable": true
},
"call": {
"$ref": "#/components/schemas/CallRecord",
"nullable": true
}
},
"required": [
"success",
"callId"
]
},
"RerunCallAnalysisResponse": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"callId": {
"type": "string"
},
"call": {
"$ref": "#/components/schemas/CallRecord",
"nullable": true
}
},
"required": [
"success",
"callId"
]
}
}
}
}