{ "openapi": "3.0.3", "info": { "title": "Tunk API reference", "version": "1.0.0", "description": "Build with the Tunk API. Manage agents, place calls, run batches, and receive signed webhook events. Start with the [quickstart](/docs/api-quickstart) or choose a resource in the sidebar.\n\n## Authentication\nSend `X-Api-Key` and `X-Workspace-Id` with each request. Use `Idempotency-Key` for every POST: a new key for each operation, the same key and body for a retry. [Authentication guide](/docs/api-keys).\n\n## Base URL\n`https://api.tunk.ai/agent/v1`\n\n## Responses\nSuccessful JSON responses generally use `{status: \"success\", data: ...}`. Paginated lists include pagination inside `data`; batch execution returns its own status and message. Each endpoint documents its response shape.\n\n## Webhooks\nSubscribe to `call.completed` for signed post-call events. Recording and analytics may be null. Verify the signature before accepting a delivery. [Webhook guide](/docs/webhooks).\n\n## Speech-to-Text\nUpload audio, run synchronous or asynchronous transcription, and retrieve or delete transcripts using the Speech to Text sections below. These endpoints belong to the separate STT service and use an API key directly in the Authorization header (no Bearer prefix). The workspace and idempotency headers described above apply to Voice AI, not STT. STT responses use the shapes documented on each endpoint." }, "servers": [ { "url": "https://api.tunk.ai/agent/v1", "description": "Production" }, { "url": "http://localhost:3001/v1", "description": "Local backend (change port to match your server)" } ], "security": [ { "apiKeyAuth": [] } ], "tags": [ { "name": "Calls" }, { "name": "Batch calls" }, { "name": "Agents" }, { "name": "Phone numbers" }, { "name": "Knowledge base" }, { "name": "Webhooks" }, { "name": "Usage" }, { "name": "Speech to Text - Audio File Upload", "description": "Upload audio or video files for transcription processing." }, { "name": "Speech to Text - Transcription", "description": "Initiate synchronous or asynchronous transcription jobs with speaker diarization, alignment, and translation." } ], "paths": { "/agents": { "post": { "tags": ["Agents"], "summary": "Create an agent", "operationId": "post_agents", "description": "Create an agent", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "agent_name": { "type": "string" } } } } }, "example": { "status": "success", "data": { "agent_id": "123e4567-e89b-42d3-a456-426614174000", "agent_name": "Support agent" } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_config": { "type": "object", "properties": { "agent_name": { "type": "string", "minLength": 1 }, "agent_welcome_message": { "type": "string" }, "webhook_url": { "type": "string", "format": "uri", "nullable": true }, "agent_type": { "type": "string", "enum": ["other", "knowledgebase_agent", "knowledge_base_agent", "graph_agent", "simple_llm_agent"], "default": "other" }, "agent_prompt": { "type": "string", "default": "" }, "llm_agent": { "type": "object", "additionalProperties": {} }, "synthesizer": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "polly", "elevenlabs", "openai", "deepgram", "azuretts", "cartesia", "smallest", "sarvam", "rime", "google", "pixa", "gemini" ] }, "provider_config": { "type": "object", "additionalProperties": {} }, "stream": { "type": "boolean", "default": false }, "buffer_size": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 40 }, "audio_format": { "type": "string", "enum": ["wav", "mp3", "pcm", "flac", "ogg"], "nullable": true }, "caching": { "type": "boolean", "default": true }, "language": { "type": "string" } }, "required": ["provider"], "additionalProperties": false }, "transcriber": { "type": "object", "properties": { "model": { "type": "string", "default": "nova-2" }, "language": { "type": "string" }, "stream": { "type": "boolean", "default": false }, "sampling_rate": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 16000 }, "encoding": { "type": "string", "enum": ["linear16", "mulaw", "alaw", "ogg_opus", "speex_with_header_byte"], "default": "linear16" }, "endpointing": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "default": 500 }, "keywords": { "type": "string", "nullable": true }, "task": { "type": "string", "default": "transcribe" }, "provider": { "type": "string", "enum": [ "deepgram", "whisper", "assembly", "azure", "smallest", "sarvam", "google", "pixa", "gladia", "elevenlabs", "openai", "soniox" ], "default": "deepgram" } }, "additionalProperties": false }, "call_analysis_config": { "type": "object", "properties": { "summary": { "type": "boolean" }, "summary_prompt": { "type": "string", "nullable": true }, "data_extraction": { "type": "boolean" }, "data_extraction_fields": { "type": "array", "items": { "type": "object", "properties": { "field_name": { "type": "string" }, "data_type": { "type": "string" }, "description": { "type": "string", "nullable": true } }, "required": ["field_name"], "additionalProperties": false }, "nullable": true }, "disposition_fields": { "type": "array", "items": { "type": "object", "properties": { "field_name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "action": { "type": "object", "properties": { "name": { "type": "string" }, "metadata": {} }, "required": ["name"], "additionalProperties": false, "nullable": true } }, "required": ["field_name"], "additionalProperties": false }, "nullable": true }, "sentiment": { "type": "boolean" }, "sentiment_prompt": { "type": "string", "nullable": true } }, "required": ["summary", "data_extraction", "sentiment"], "additionalProperties": false }, "api_tools": {}, "call_transfer_config": {}, "task_config": { "type": "object", "properties": { "optimize_latency": { "type": "boolean", "default": true }, "hangup_after_silence": { "type": "integer", "default": 20 }, "incremental_delay": { "type": "integer", "default": 900 }, "number_of_words_for_interruption": { "type": "integer", "default": 1 }, "interruption_backoff_period": { "type": "integer", "default": 100 }, "hangup_after_LLMCall": { "type": "boolean", "default": false }, "call_cancellation_prompt": { "type": "string", "nullable": true }, "end_call_tool_mode": { "type": "string", "nullable": true }, "call_hangup_message": { "anyOf": [ { "type": "string", "nullable": true }, { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true } ] }, "backchanneling": { "type": "boolean", "default": false }, "backchanneling_message_gap": { "type": "integer", "default": 5 }, "backchanneling_start_delay": { "type": "integer", "default": 5 }, "ambient_noise": { "type": "boolean", "default": false }, "ambient_noise_track": { "type": "string", "default": "convention_hall" }, "call_terminate": { "type": "integer", "default": 300 }, "use_fillers": { "type": "boolean", "default": false }, "trigger_user_online_message_after": { "type": "integer", "default": 10 }, "check_user_online_message": { "type": "string", "default": "Hey, are you still there" }, "check_if_user_online": { "type": "boolean", "default": true }, "generate_precise_transcript": { "type": "boolean", "default": false } }, "additionalProperties": false }, "status": { "type": "string", "enum": ["active", "inactive", "seeding"] }, "repository_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "tool_definition_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "input": { "type": "object", "properties": { "provider": { "type": "string" }, "format": { "type": "string" } }, "required": ["provider", "format"], "additionalProperties": false, "nullable": true }, "output": { "type": "object", "properties": { "provider": { "type": "string" }, "format": { "type": "string" } }, "required": ["provider", "format"], "additionalProperties": false, "nullable": true }, "language": { "type": "string" }, "timezone": { "type": "string", "enum": ["IST", "UTC", "EST", "CST", "PST", "GMT", "CET", "GST", "SGT", "JST", "AEST", "IST_IRAN", "PKT", "BDT"] }, "call_type": { "type": "string", "enum": ["inbound", "outbound"] }, "phone_number": { "type": "string" }, "phone_number_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" } }, "required": ["agent_name", "llm_agent"], "additionalProperties": false } }, "required": ["agent_config"], "additionalProperties": false }, "example": { "agent_config": { "agent_name": "Support agent", "agent_prompt": "Help customers with support questions.", "llm_agent": {} } } } } } }, "get": { "tags": ["Agents"], "summary": "List agents", "operationId": "get_agents", "description": "List agents", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next_page": { "type": "boolean" }, "has_prev_page": { "type": "boolean" } } } } } } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agents/{id}": { "get": { "tags": ["Agents"], "summary": "Get an agent", "operationId": "get_agents__id_", "description": "Get an agent", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": ["Agents"], "summary": "Update an agent", "operationId": "patch_agents__id_", "description": "Update an agent", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_config": { "type": "object", "properties": { "agent_name": { "type": "string" }, "language": { "type": "string" }, "timezone": { "type": "string", "enum": ["IST", "UTC", "EST", "CST", "PST", "GMT", "CET", "GST", "SGT", "JST", "AEST", "IST_IRAN", "PKT", "BDT"] }, "repository_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "tool_definition_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "agent_type": { "type": "string", "enum": ["other", "knowledgebase_agent", "knowledge_base_agent", "graph_agent", "simple_llm_agent"] }, "agent_prompt": { "type": "string" }, "agent_welcome_message": { "type": "string", "nullable": true }, "webhook_url": { "type": "string", "nullable": true }, "llm_agent": { "type": "object", "properties": { "agent_flow_type": { "type": "string" }, "agent_type": { "type": "string" }, "routes": { "type": "object", "properties": { "embedding_model": { "type": "string" }, "routes": { "type": "array" } }, "additionalProperties": false, "nullable": true }, "llm_config": { "type": "object", "properties": { "model": { "type": "string" }, "max_tokens": { "type": "number" }, "family": { "type": "string" }, "temperature": { "type": "number" }, "request_json": { "type": "boolean" }, "stop": { "type": "array", "items": { "type": "string" }, "nullable": true }, "top_k": { "type": "number" }, "top_p": { "type": "number" }, "min_p": { "type": "number" }, "frequency_penalty": { "type": "number" }, "presence_penalty": { "type": "number" }, "provider": { "type": "string" }, "base_url": { "type": "string" }, "routes": { "type": "object", "properties": { "embedding_model": { "type": "string" }, "routes": { "type": "array" } }, "additionalProperties": false, "nullable": true }, "vector_store": { "type": "object", "properties": { "provider": { "type": "string" }, "provider_config": { "type": "object", "properties": { "vector_id": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "synthesizer": { "type": "object", "properties": { "provider": { "type": "string" }, "provider_config": { "type": "object", "properties": { "voice": { "type": "string" }, "voice_id": { "type": "string" }, "model": { "type": "string", "nullable": true }, "temperature": { "type": "number" }, "similarity_boost": { "type": "number" }, "language": { "type": "string" }, "engine": { "type": "string", "nullable": true } }, "additionalProperties": false }, "stream": { "type": "boolean" }, "buffer_size": { "type": "number" }, "audio_format": { "type": "string", "enum": ["wav", "mp3", "pcm", "flac", "ogg"], "nullable": true }, "caching": { "type": "boolean" }, "language": { "type": "string" } }, "additionalProperties": false }, "transcriber": { "type": "object", "properties": { "model": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true }, "stream": { "type": "boolean" }, "sampling_rate": { "type": "number" }, "encoding": { "type": "string" }, "endpointing": { "type": "number" }, "keywords": { "type": "string", "nullable": true }, "task": { "type": "string" }, "provider": { "type": "string" } }, "additionalProperties": false }, "call_analysis_config": { "type": "object", "properties": { "summary": { "type": "boolean" }, "summary_prompt": { "type": "string", "nullable": true }, "data_extraction": { "type": "boolean" }, "data_extraction_fields": { "type": "array", "items": { "type": "object", "properties": { "field_name": { "type": "string" }, "data_type": { "type": "string" }, "description": { "type": "string", "nullable": true } }, "required": ["field_name"], "additionalProperties": false }, "nullable": true }, "disposition_fields": { "type": "array", "items": { "type": "object", "properties": { "field_name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "action": { "type": "object", "properties": { "name": { "type": "string" }, "metadata": {} }, "required": ["name"], "additionalProperties": false, "nullable": true } }, "required": ["field_name"], "additionalProperties": false }, "nullable": true }, "sentiment": { "type": "boolean" }, "sentiment_prompt": { "type": "string", "nullable": true } }, "required": ["summary", "data_extraction", "sentiment"], "additionalProperties": false }, "api_tools": {}, "input": { "type": "object", "properties": { "provider": { "type": "string" }, "format": { "type": "string" } }, "additionalProperties": false }, "output": { "type": "object", "properties": { "provider": { "type": "string" }, "format": { "type": "string" } }, "additionalProperties": false }, "task_config": { "type": "object", "additionalProperties": {} } }, "additionalProperties": false } }, "required": ["agent_config"], "additionalProperties": false } } } } }, "delete": { "tags": ["Agents"], "summary": "Delete an agent", "operationId": "delete_agents__id_", "description": "Delete an agent", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch-calls": { "post": { "tags": ["Batch calls"], "summary": "Create a batch call with recipients (single request)", "operationId": "post_batch_calls", "description": "Create or list batches. POST without schedule_time saves recipients without executing; with schedule_time it also schedules calls.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "recipient_count": { "type": "integer" }, "schedule_id": { "type": "string", "format": "uuid", "nullable": true }, "schedule_time": { "type": "string", "format": "date-time", "nullable": true } }, "required": ["batch_id", "name", "agent_id", "status", "recipient_count"], "additionalProperties": false } } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3 }, "agent_id": { "type": "string", "format": "uuid" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "phone_number": { "type": "string", "minLength": 5 }, "variables": { "type": "object", "additionalProperties": {} } }, "required": ["phone_number"], "additionalProperties": false }, "minItems": 1, "maxItems": 10000 }, "schedule_time": { "type": "string", "format": "date-time" } }, "required": ["name", "agent_id", "recipients"], "additionalProperties": false }, "example": { "name": "Follow-up calls", "agent_id": "123e4567-e89b-42d3-a456-426614174000", "recipients": [ { "phone_number": "+14155552671", "variables": { "customer_name": "Alex" } } ] } } } } }, "get": { "tags": ["Batch calls"], "summary": "List batch calls", "operationId": "get_batch_calls", "description": "Create or list batches. POST without schedule_time saves recipients without executing; with schedule_time it also schedules calls.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next_page": { "type": "boolean" }, "has_prev_page": { "type": "boolean" } } } } } } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch-calls/{id}/execute": { "post": { "tags": ["Batch calls"], "summary": "Execute a previously created batch call", "operationId": "post_batch_calls__id__execute", "description": "Queue execution now or schedule it for later. Equivalent execution flow to /batch/run/{batch_id}.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Schedule accepted; execution is asynchronous", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["scheduled"] }, "schedule_id": { "type": "string", "format": "uuid" }, "schedule_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "message": { "type": "string" } } }, "example": { "batch_id": "123e4567-e89b-42d3-a456-426614174000", "status": "scheduled", "schedule_id": "123e4567-e89b-42d3-a456-426614174000", "schedule_time": "2030-01-15T03:30:00.000Z", "end_time": "2030-01-15T12:30:00.000Z", "timezone": "Asia/Kolkata", "message": "Batch execution scheduled" } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "schedule_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "nullable": true } ] }, "example": {} } } } } }, "/batch-calls/{id}": { "get": { "tags": ["Batch calls"], "summary": "Get a batch call", "operationId": "get_batch_calls__id_", "description": "Get a batch call", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch/create": { "post": { "tags": ["Batch calls"], "summary": "Create a batch campaign (JSON recipients or CSV multipart)", "operationId": "post_batch_create", "description": "Create a draft batch with recipients using JSON or a multipart CSV. Supplying schedule_time also creates and queues a schedule; otherwise execute separately. See [batch calls](/docs/batch-calls).", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid" }, "batch_name": { "type": "string" }, "name": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "recipient_count": { "type": "integer" }, "total_calls": { "type": "integer" }, "concurrency_limit": { "type": "integer", "nullable": true }, "schedule_id": { "type": "string", "format": "uuid", "nullable": true }, "schedule_time": { "type": "string", "format": "date-time", "nullable": true } } } } }, "example": { "status": "success", "data": { "batch_id": "123e4567-e89b-42d3-a456-426614174000", "batch_name": "Follow-up calls", "name": "Follow-up calls", "agent_id": "123e4567-e89b-42d3-a456-426614174000", "status": "draft", "recipient_count": 1, "total_calls": 1, "concurrency_limit": null, "schedule_id": null, "schedule_time": null } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "batch_name": { "type": "string", "minLength": 3 }, "name": { "type": "string", "minLength": 3 }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "phone_number": { "type": "string", "minLength": 5 }, "metadata": { "type": "object", "additionalProperties": {} }, "variables": { "type": "object", "additionalProperties": {} } }, "required": ["phone_number"], "additionalProperties": false }, "minItems": 1, "maxItems": 10000 }, "schedule_time": { "type": "string", "format": "date-time" }, "concurrent_calls": { "type": "integer", "minimum": 1 }, "execution_window": { "type": "object", "properties": { "start_time": { "type": "string" }, "end_time": { "type": "string" }, "timezone": { "type": "string" } } } }, "required": ["agent_id", "recipients"], "additionalProperties": false, "anyOf": [ { "required": ["name"] }, { "required": ["batch_name"] } ] }, "example": { "batch_name": "Follow-up calls", "agent_id": "123e4567-e89b-42d3-a456-426614174000", "recipients": [ { "phone_number": "+14155552671", "variables": { "customer_name": "Alex" } } ] } }, "multipart/form-data": { "schema": { "type": "object", "required": ["agent_id", "batch_name", "file"], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "batch_name": { "type": "string", "minLength": 3 }, "file": { "type": "string", "format": "binary", "description": "CSV containing phone_number and optional metadata columns" }, "schedule_time": { "type": "string", "format": "date-time" }, "concurrent_calls": { "type": "integer", "minimum": 1 }, "execution_window": { "type": "string", "description": "JSON encoded execution-window object" } } } } } } } }, "/batch/run/{batch_id}": { "post": { "tags": ["Batch calls"], "summary": "Run a batch campaign", "operationId": "post_batch_run__batch_id_", "description": "Queue execution now with an empty body, or later with schedule_time. Returns 202 Accepted and a schedule, not a completed batch. Use resume for paused campaigns.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Schedule accepted; execution is asynchronous", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["scheduled"] }, "schedule_id": { "type": "string", "format": "uuid" }, "schedule_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "message": { "type": "string" } } }, "example": { "batch_id": "123e4567-e89b-42d3-a456-426614174000", "status": "scheduled", "schedule_id": "123e4567-e89b-42d3-a456-426614174000", "schedule_time": "2030-01-15T03:30:00.000Z", "end_time": "2030-01-15T12:30:00.000Z", "timezone": "Asia/Kolkata", "message": "Batch execution scheduled" } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "anyOf": [ { "not": {} }, { "type": "object", "properties": { "schedule_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "nullable": true } ] }, "example": { "schedule_time": "2030-01-15T09:00:00+05:30", "end_time": "2030-01-15T18:00:00+05:30", "timezone": "Asia/Kolkata" } } } } } }, "/batch/pause/{batch_id}": { "post": { "tags": ["Batch calls"], "summary": "Pause a batch campaign", "operationId": "post_batch_pause__batch_id_", "description": "Pause a batch campaign", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch/resume/{batch_id}": { "post": { "tags": ["Batch calls"], "summary": "Resume a paused batch campaign", "operationId": "post_batch_resume__batch_id_", "description": "Resume a paused batch campaign", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch/terminate/{batch_id}": { "post": { "tags": ["Batch calls"], "summary": "Terminate a running batch campaign", "operationId": "post_batch_terminate__batch_id_", "description": "Terminate a running batch campaign", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch/delete/{batch_id}": { "delete": { "tags": ["Batch calls"], "summary": "Delete a batch campaign and its logs", "operationId": "delete_batch_delete__batch_id_", "description": "Delete a batch campaign and its logs", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch/{batch_id}": { "delete": { "tags": ["Batch calls"], "summary": "Delete a batch campaign and its logs", "operationId": "delete_batch__batch_id_", "description": "Delete a batch campaign and its logs", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch/retry": { "post": { "tags": ["Batch calls"], "summary": "Retry failed calls from one or more batches", "operationId": "post_batch_retry", "description": "Retry failed calls from one or more batches", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "batch_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "batch_name": { "type": "string" }, "include_status": { "type": "array", "items": { "type": "string" } }, "includeStatus": { "type": "array", "items": { "type": "string" } } }, "required": ["batch_ids"], "additionalProperties": false }, "example": { "agent_id": "123e4567-e89b-42d3-a456-426614174000", "batch_ids": ["123e4567-e89b-42d3-a456-426614174000"], "include_status": ["failed"] } } } } } }, "/batch/calls/{batch_id}": { "get": { "tags": ["Batch calls"], "summary": "List calls in a batch campaign", "operationId": "get_batch_calls__batch_id_", "description": "List calls in a batch campaign", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/batch/export/{batch_id}": { "post": { "tags": ["Batch calls"], "summary": "Export batch call logs as Excel", "operationId": "post_batch_export__batch_id_", "description": "Export batch call logs as Excel", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Excel file download", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/phone-mappings": { "post": { "tags": ["Phone numbers"], "summary": "Create a phone–agent mapping", "operationId": "post_phone_mappings", "description": "Create a phone–agent mapping", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "call_type": { "type": "string", "enum": ["inbound", "outbound"] }, "status": { "type": "string", "enum": ["active", "inactive"], "default": "active" } }, "required": ["phone_number_id", "agent_id", "call_type"], "additionalProperties": false }, "example": { "phone_number_id": "123e4567-e89b-42d3-a456-426614174000", "agent_id": "123e4567-e89b-42d3-a456-426614174000", "call_type": "outbound" } } } } }, "get": { "tags": ["Phone numbers"], "summary": "List phone–agent mappings", "operationId": "get_phone_mappings", "description": "List phone–agent mappings", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/phone-mappings/{id}": { "get": { "tags": ["Phone numbers"], "summary": "Get a phone–agent mapping", "operationId": "get_phone_mappings__id_", "description": "Get a phone–agent mapping", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/call": { "post": { "tags": ["Calls"], "summary": "Place an outbound call", "operationId": "post_call", "description": "Places a real outbound call. The agent needs an owned outbound number mapping. Optional caller-number overrides must belong to the account. The response is dispatch acceptance, not confirmation that the recipient answered. See the [API quickstart](/docs/api-quickstart).", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "session_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "recipient_phone_number": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "from_phone_number": { "type": "string" } } } } }, "example": { "status": "success", "data": { "session_id": "123e4567-e89b-42d3-a456-426614174000", "status": "queued", "recipient_phone_number": "+14155552671", "agent_id": "123e4567-e89b-42d3-a456-426614174000" } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "recipient_phone_number": { "type": "string", "minLength": 5 }, "from_phone_number": { "type": "string", "minLength": 5 }, "from_phone_number_id": { "type": "string", "format": "uuid" }, "call_metadata": { "type": "object", "additionalProperties": {} }, "is_recording": { "type": "boolean" } }, "required": ["agent_id", "recipient_phone_number"], "additionalProperties": false }, "example": { "agent_id": "123e4567-e89b-42d3-a456-426614174000", "recipient_phone_number": "+14155552671", "is_recording": true, "call_metadata": { "customer_name": "Alex" } } } } } } }, "/call/detail/{session_id}": { "get": { "tags": ["Calls"], "summary": "Get call detail, transcript, and extraction", "operationId": "get_call_detail__session_id_", "description": "Get call detail, transcript, and extraction", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "$ref": "#/components/schemas/CallDetail" } } }, "example": { "status": "success", "data": { "session_id": "d9416526-8334-4a6a-b943-376c37588537", "agent_id": "123e4567-e89b-42d3-a456-426614174000", "created_at": "2030-01-15T04:30:00.000Z", "sentiment": "positive", "disposition": "Appointment Booked", "summary": "Customer called to confirm their vehicle maintenance appointment.", "data_extraction": { "customer_name": "Alex", "appointment_date": "2030-01-16" }, "transcript": [ { "speaker": "assistant", "text": "Hello, how can I help you today?" } ], "recording_url": "https://recordings.tunk.ai/sample.wav" } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/calls": { "get": { "tags": ["Calls"], "summary": "List call sessions", "operationId": "get_calls", "description": "List call sessions", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "batch_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "from_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "call_status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to_phone_number", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "disposition", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort_key", "in": "query", "required": false, "schema": { "type": "string", "enum": ["created_at", "call_duration"] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CallSummaryItem" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next_page": { "type": "boolean" }, "has_prev_page": { "type": "boolean" } } } } } } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/calls/{agent_id}": { "get": { "tags": ["Calls"], "summary": "List call sessions for an agent", "operationId": "get_calls__agent_id_", "description": "List call sessions for an agent", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "batch_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "from_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "call_status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to_phone_number", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "disposition", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort_key", "in": "query", "required": false, "schema": { "type": "string", "enum": ["created_at", "call_duration"] } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "enum": ["asc", "desc"] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CallSummaryItem" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next_page": { "type": "boolean" }, "has_prev_page": { "type": "boolean" } } } } } } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/knowledge-base/repository": { "post": { "tags": ["Knowledge base"], "summary": "Create a knowledge base repository", "operationId": "post_knowledge_base_repository", "description": "Create a knowledge base repository", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": ["name"], "additionalProperties": false }, "example": { "name": "Support documents" } } } } }, "get": { "tags": ["Knowledge base"], "summary": "List knowledge base repositories", "operationId": "get_knowledge_base_repository", "description": "List knowledge base repositories", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next_page": { "type": "boolean" }, "has_prev_page": { "type": "boolean" } } } } } } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/knowledge-base/repository/{id}": { "delete": { "tags": ["Knowledge base"], "summary": "Delete a knowledge base repository", "operationId": "delete_knowledge_base_repository__id_", "description": "Delete a knowledge base repository", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/knowledge-base/upload": { "post": { "tags": ["Knowledge base"], "summary": "Upload a knowledge base document file", "operationId": "post_knowledge_base_upload", "description": "Upload a knowledge base document file", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["repository_id", "file"], "properties": { "repository_id": { "type": "string", "format": "uuid" }, "file": { "type": "string", "format": "binary" }, "file_type": { "type": "string", "enum": ["pdf", "docx", "txt", "json", "html", "web"] } } } } } } } }, "/knowledge-base": { "post": { "tags": ["Knowledge base"], "summary": "Add a knowledge base item (URL, text, or existing file path)", "operationId": "post_knowledge_base", "description": "Add a knowledge base item (URL, text, or existing file path)", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "repository_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": ["url"] }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string", "minLength": 1 } }, "required": ["repository_id", "type", "url"], "additionalProperties": false }, { "type": "object", "properties": { "repository_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": ["text"] }, "content": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 } }, "required": ["repository_id", "type", "content"], "additionalProperties": false }, { "type": "object", "properties": { "repository_id": { "type": "string", "format": "uuid" }, "file_type": { "type": "string", "enum": ["pdf", "docx", "txt", "json", "html", "web"] }, "file_name": { "type": "string", "minLength": 1 }, "file_path": { "type": "string", "minLength": 1 } }, "required": ["repository_id", "file_type", "file_name", "file_path"], "additionalProperties": false } ] }, "example": { "repository_id": "123e4567-e89b-42d3-a456-426614174000", "type": "text", "content": "Our support hours are 9am to 5pm." } } } } } }, "/knowledge-base/items/{repo_id}": { "get": { "tags": ["Knowledge base"], "summary": "List knowledge base items in a repository", "operationId": "get_knowledge_base_items__repo_id_", "description": "List knowledge base items in a repository", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "repo_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next_page": { "type": "boolean" }, "has_prev_page": { "type": "boolean" } } } } } } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/knowledge-base/{id}/status": { "get": { "tags": ["Knowledge base"], "summary": "Get knowledge base item ingestion status", "operationId": "get_knowledge_base__id__status", "description": "Get knowledge base item ingestion status", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/knowledge-base/{id}": { "get": { "tags": ["Knowledge base"], "summary": "Get a knowledge base item", "operationId": "get_knowledge_base__id_", "description": "Get a knowledge base item", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": ["Knowledge base"], "summary": "Update a knowledge base item", "operationId": "put_knowledge_base__id_", "description": "Update a knowledge base item", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "file_name": { "type": "string" }, "title": { "type": "string" } }, "additionalProperties": true } } } } }, "delete": { "tags": ["Knowledge base"], "summary": "Delete a knowledge base item", "operationId": "delete_knowledge_base__id_", "description": "Delete a knowledge base item", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/knowledge-base/{id}/retry": { "post": { "tags": ["Knowledge base"], "summary": "Retry failed knowledge base ingestion", "operationId": "post_knowledge_base__id__retry", "description": "Retry ingestion of an existing knowledge-base item.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/phone-numbers": { "get": { "tags": ["Phone numbers"], "summary": "List configured phone numbers", "operationId": "get_phone_numbers", "description": "List configured phone numbers", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": true, "minimum": 0, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/phone-numbers/import/{provider}": { "post": { "tags": ["Phone numbers"], "summary": "Import a phone number from a provider", "operationId": "post_phone_numbers_import__provider_", "description": "Import an owned number using provider credentials. This public route accepts twilio, plivo or carrierx; Vonage is not a supported import value here.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": ["twilio", "plivo", "carrierx"] } } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "phone_number": { "type": "string", "minLength": 10 }, "country_code": { "type": "string", "minLength": 1, "maxLength": 5 }, "sid": { "type": "string" }, "auth_token": { "type": "string" }, "auth_sid": { "type": "string" }, "auth_secret": { "type": "string" }, "access_token": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" } }, "required": ["phone_number", "country_code"], "additionalProperties": false } } } } } }, "/phone-numbers/dnd": { "post": { "tags": ["Phone numbers"], "summary": "Add a number to the Do Not Call registry", "operationId": "post_phone_numbers_dnd", "description": "Manage Do Not Call entries. POST associates the blocked number with phone_number_id, or the first owned number if omitted. The accepted reason field is not persisted by this route.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string", "minLength": 5 }, "reason": { "type": "string" }, "phone_number_id": { "type": "string", "format": "uuid" } }, "required": ["phone_number"], "additionalProperties": false } } } } }, "get": { "tags": ["Phone numbers"], "summary": "List Do Not Call entries", "operationId": "get_phone_numbers_dnd", "description": "Manage Do Not Call entries. POST associates the blocked number with phone_number_id, or the first owned number if omitted. The accepted reason field is not persisted by this route.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/phone-numbers/dnd/{id}": { "delete": { "tags": ["Phone numbers"], "summary": "Remove a number from the Do Not Call registry", "operationId": "delete_phone_numbers_dnd__id_", "description": "Remove a number from the Do Not Call registry", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/usage": { "get": { "tags": ["Usage"], "summary": "Get usage for workspace", "operationId": "get_usage", "description": "Get usage for workspace", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["llm", "tts", "stt"] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/usage/summary": { "get": { "tags": ["Usage"], "summary": "Get usage summary for workspace", "operationId": "get_usage_summary", "description": "Get usage summary for workspace", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["llm", "tts", "stt"] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks": { "post": { "tags": ["Webhooks"], "summary": "Register a webhook endpoint", "operationId": "post_webhooks", "description": "Register or list workspace-scoped signed webhook subscriptions. Only call.completed is supported. Creation returns secret once; list/get never expose it. Omit agent_id or use null for all agents in the workspace. See [webhooks](/docs/webhooks).", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "webhook_id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "type": "string" } }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] }, "secret": { "type": "string" } }, "required": ["webhook_id", "url", "events", "status", "created_at", "updated_at", "secret"], "additionalProperties": false } } }, "example": { "status": "success", "data": { "webhook_id": "123e4567-e89b-42d3-a456-426614174000", "url": "https://your-domain.com/webhooks/tunk", "events": ["call.completed"], "agent_id": null, "description": "CRM integration", "status": "active", "created_at": "2030-01-15T04:30:00.000Z", "updated_at": "2030-01-15T04:30:00.000Z", "secret": "whsec_" } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string", "maxLength": 255 }, "events": { "type": "array", "items": { "type": "string", "enum": ["call.completed"] }, "minItems": 1, "default": ["call.completed"] }, "agent_id": { "type": "string", "format": "uuid", "nullable": true } }, "required": ["url"], "additionalProperties": false }, "example": { "url": "https://your-domain.com/webhooks/tunk", "events": ["call.completed"], "agent_id": "123e4567-e89b-42d3-a456-426614174000", "description": "CRM call results" } } } }, "callbacks": { "callCompleted": { "{$request.body#/url}": { "post": { "summary": "Signed call.completed delivery to your receiver", "description": "A post-call snapshot. Recording and analytics are not prerequisites. Verify the raw body HMAC, timestamp and event ID; durably accept before responding. See /docs/webhooks for the receiver example and retry behavior.", "security": [], "parameters": [ { "name": "X-Tunk-Webhook-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Tunk-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Tunk-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": ["call.completed"] } }, { "name": "X-Tunk-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix seconds for this attempt" }, { "name": "X-Tunk-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1= over timestamp + dot + raw body" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallCompletedEvent" } } } }, "responses": { "204": { "description": "Receiver durably accepted the event (any 2xx succeeds)" }, "500": { "description": "Receiver failed; queued deliveries can retry" } } } } } } }, "get": { "tags": ["Webhooks"], "summary": "List webhook endpoints", "operationId": "get_webhooks", "description": "Register or list workspace-scoped signed webhook subscriptions. Only call.completed is supported. Creation returns secret once; list/get never expose it. Omit agent_id or use null for all agents in the workspace. See [webhooks](/docs/webhooks).", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "webhook_id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "type": "string" } }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] } }, "required": ["webhook_id", "url", "events", "status", "created_at", "updated_at"], "additionalProperties": false } }, "pagination": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{id}": { "get": { "tags": ["Webhooks"], "summary": "Get a webhook endpoint", "operationId": "get_webhooks__id_", "description": "Retrieve, update or delete a registered endpoint in the current workspace. Use status active or disabled to control delivery.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "webhook_id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "type": "string" } }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] } }, "required": ["webhook_id", "url", "events", "status", "created_at", "updated_at"], "additionalProperties": false } } }, "example": { "status": "success", "data": { "webhook_id": "123e4567-e89b-42d3-a456-426614174000", "url": "https://your-domain.com/webhooks/tunk", "events": ["call.completed"], "agent_id": null, "description": "CRM integration", "status": "active", "created_at": "2030-01-15T04:30:00.000Z", "updated_at": "2030-01-15T04:30:00.000Z" } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": ["Webhooks"], "summary": "Update a webhook endpoint", "operationId": "patch_webhooks__id_", "description": "Retrieve, update or delete a registered endpoint in the current workspace. Use status active or disabled to control delivery.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "webhook_id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "type": "string" } }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] } }, "required": ["webhook_id", "url", "events", "status", "created_at", "updated_at"], "additionalProperties": false } } }, "example": { "status": "success", "data": { "webhook_id": "123e4567-e89b-42d3-a456-426614174000", "url": "https://your-domain.com/webhooks/tunk", "events": ["call.completed"], "agent_id": null, "description": "CRM integration", "status": "active", "created_at": "2030-01-15T04:30:00.000Z", "updated_at": "2030-01-15T04:30:00.000Z" } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string", "maxLength": 255, "nullable": true }, "events": { "type": "array", "items": { "type": "string", "enum": ["call.completed"] }, "minItems": 1 }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": ["active", "disabled"] } }, "additionalProperties": false }, "example": { "status": "disabled" } } } } }, "delete": { "tags": ["Webhooks"], "summary": "Delete a webhook endpoint", "operationId": "delete_webhooks__id_", "description": "Retrieve, update or delete a registered endpoint in the current workspace. Use status active or disabled to control delivery.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": {} } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{id}/rotate-secret": { "post": { "tags": ["Webhooks"], "summary": "Rotate the webhook signing secret", "operationId": "post_webhooks__id__rotate_secret", "description": "Replace the signing secret and return the new secret once. The previous secret is invalid immediately; update your receiver. No overlap period.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "webhook_id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "type": "string" } }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ] }, "secret": { "type": "string" } }, "required": ["webhook_id", "url", "events", "status", "created_at", "updated_at", "secret"], "additionalProperties": false } } }, "example": { "status": "success", "data": { "webhook_id": "123e4567-e89b-42d3-a456-426614174000", "url": "https://your-domain.com/webhooks/tunk", "events": ["call.completed"], "agent_id": null, "description": "CRM integration", "status": "active", "created_at": "2030-01-15T04:30:00.000Z", "updated_at": "2030-01-15T04:30:00.000Z", "secret": "whsec_" } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/webhooks/{id}/test": { "post": { "tags": ["Webhooks"], "summary": "Send a signed test call.completed payload to the endpoint", "operationId": "post_webhooks__id__test", "description": "Send one signed synthetic call.completed payload immediately, without placing a call. Read data.status and data.http_status to verify receiver acceptance. This manual test does not use automatic retries. Use a new Idempotency-Key for each new test.", "parameters": [ { "name": "X-Workspace-Id", "in": "header", "required": true, "description": "Workspace UUID. A workspace-bound key can supply the scope; include this header for portable clients.", "schema": { "type": "string", "format": "uuid" }, "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per logical operation. Reuse only for retrying the same request; cached for 24 hours.", "schema": { "type": "string" }, "example": "123e4567-e89b-42d3-a456-426614174000" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": ["status", "data"], "properties": { "status": { "type": "string", "enum": ["success"] }, "data": { "type": "object", "properties": { "webhook_id": { "type": "string", "format": "uuid" }, "delivery_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": ["success", "failed"] }, "http_status": { "type": "integer", "nullable": true } } } } }, "example": { "status": "success", "data": { "webhook_id": "123e4567-e89b-42d3-a456-426614174000", "delivery_id": "123e4567-e89b-42d3-a456-426614174000", "status": "success", "http_status": 204 } } } } }, "400": { "description": "Invalid input or missing idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing, invalid or inactive API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Workspace access denied or mismatched key binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "411": { "description": "Missing workspace scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/file/upload": { "post": { "tags": ["Speech to Text - Audio File Upload"], "summary": "Upload Audio/Video File for Transcription", "description": "Upload an audio or video file for transcription. The file size must be under 500 MB. Uploaded media is securely stored on Tunk storage and accessible for transcription processing.\n\n**Supported formats:** `mp4`, `mov`, `oga`, `wav`, `avi`, `wmv`, `ogg`, `amr`, `m4a`, `mp3`, `mkv`, `awb`, `aac`, `wma`.", "operationId": "uploadFile", "security": [ { "SttApiKey": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["file"], "properties": { "file": { "type": "string", "format": "binary", "description": "The audio or video file to be uploaded (max 500 MB)." } } } } } }, "responses": { "200": { "description": "File uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "file_url": { "type": "string", "format": "uri", "description": "The secure URL of the uploaded file." } } }, "example": { "file_url": "https://tunk.s3.amazonaws.com/media_files/232ea175-b25c-4096-93fd-1138e4e31574/audio_gettysburg_EmhW.wav" } } } }, "400": { "$ref": "#/components/responses/SttBadRequest" }, "401": { "$ref": "#/components/responses/SttUnauthorized" }, "422": { "$ref": "#/components/responses/SttUnprocessableEntity" }, "500": { "$ref": "#/components/responses/SttInternalServerError" } } }, "servers": [ { "url": "https://api.tunk.ai/v1", "description": "Speech-to-Text production" } ] }, "/transcription/run-async": { "post": { "tags": ["Speech to Text - Transcription"], "summary": "Asynchronous Transcription Job", "description": "Initiate an asynchronous transcription job on an audio/video file with optional speaker diarization, English translation, word-level forced alignment, summarization, and LLM sentiment analysis. When processing completes, results are dispatched to your configured `webhook_url`.", "operationId": "runTranscriptionAsync", "security": [ { "SttApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["file_url", "webhook_url"], "properties": { "file_url": { "type": "string", "format": "uri", "description": "Publicly accessible URL of the audio/video file to transcribe." }, "language": { "type": "string", "default": "auto-detect", "description": "Spoken language code (e.g. `en`, `es`, `hi`, `fr`, `de`) or `auto-detect`." }, "diarization": { "type": "boolean", "default": false, "description": "Enable speaker diarization to label distinct speakers." }, "translation": { "type": "boolean", "default": false, "description": "Translate non-English audio content to English." }, "forced_alignment": { "type": "boolean", "default": false, "description": "Enable word-level timestamps and alignment." }, "summarization": { "type": "boolean", "default": false, "description": "Generate an executive summary of the conversation transcript." }, "sentiment_analysis_by_llm": { "type": "boolean", "default": false, "description": "Run sentiment analysis on transcript segments." }, "webhook_url": { "type": "string", "format": "uri", "description": "Endpoint URL to receive transcription results upon job completion." }, "webhook_auth_header": { "type": "string", "description": "Custom authorization header name sent to your webhook (e.g. `Authorization` or `X-Webhook-Secret`)." }, "webhook_auth_secret": { "type": "string", "description": "Header value sent with webhook request." }, "webhook_metadata": { "type": "object", "description": "Custom metadata payload forwarded verbatim into the webhook body." } } }, "example": { "file_url": "https://your-audio-file-url.com/audio.mp3", "language": "en", "diarization": true, "translation": false, "forced_alignment": true, "summarization": true, "sentiment_analysis_by_llm": true, "webhook_url": "https://api.yourcompany.com/webhooks/transcription", "webhook_auth_header": "Authorization", "webhook_auth_secret": "Bearer sec_live_9921", "webhook_metadata": { "job_id": "job_48291", "customer_id": "cust_8829" } } } } }, "responses": { "200": { "description": "Transcription job queued successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique transcription job ID" }, "status": { "type": "string", "enum": ["In_Queue", "Pending", "Failed"], "example": "In_Queue" } } }, "example": { "id": "5b294444-1b35-4074-9407-c4be7cc5f6ba", "status": "In_Queue" } } } }, "400": { "$ref": "#/components/responses/SttBadRequest" }, "401": { "$ref": "#/components/responses/SttUnauthorized" }, "500": { "$ref": "#/components/responses/SttInternalServerError" } } }, "servers": [ { "url": "https://api.tunk.ai/v1", "description": "Speech-to-Text production" } ] }, "/transcription/run": { "post": { "tags": ["Speech to Text - Transcription"], "summary": "Synchronous Transcription", "description": "Initiates a synchronous transcription request. The HTTP connection remains open until transcription, diarization, and LLM analysis are finished, returning full text, word timestamps, and summary in the immediate response.", "operationId": "runTranscriptionSync", "security": [ { "SttApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["file_url"], "properties": { "file_url": { "type": "string", "format": "uri", "description": "URL of the audio/video file." }, "language": { "type": "string", "default": "auto-detect" }, "diarization": { "type": "boolean", "default": false }, "translation": { "type": "boolean", "default": false }, "forced_alignment": { "type": "boolean", "default": false }, "summarization": { "type": "boolean", "default": false }, "sentiment_analysis_by_llm": { "type": "boolean", "default": false } } }, "example": { "file_url": "https://your-audio-file-url.com/audio.mp3", "language": "en", "diarization": true, "translation": false, "forced_alignment": true, "summarization": true, "sentiment_analysis_by_llm": false } } } }, "responses": { "200": { "description": "Transcription completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "example": "Completed" }, "duration": { "type": "number", "description": "Duration in seconds" }, "file_size": { "type": "number", "description": "File size in bytes" }, "text": { "type": "string", "description": "Full transcribed text" }, "words": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "number" }, "end": { "type": "number" }, "word": { "type": "string" }, "score": { "type": "number" }, "speaker": { "type": "string" } } } }, "segments": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "number" }, "end": { "type": "number" }, "text": { "type": "string" }, "speaker": { "type": "string" } } } }, "summary": { "type": "string" } } }, "example": { "id": "5b294444-1b35-4074-9407-c4be7cc5f6ba", "status": "Completed", "duration": 45.2, "file_size": 724890, "text": "Four score and seven years ago our fathers brought forth on this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal.", "segments": [ { "start": 0, "end": 7.5, "text": "Four score and seven years ago our fathers brought forth on this continent, a new nation...", "speaker": "SPEAKER_00" } ], "summary": "Abraham Lincoln addresses the principles of liberty and human equality." } } } }, "400": { "$ref": "#/components/responses/SttBadRequest" }, "401": { "$ref": "#/components/responses/SttUnauthorized" }, "500": { "$ref": "#/components/responses/SttInternalServerError" } } }, "servers": [ { "url": "https://api.tunk.ai/v1", "description": "Speech-to-Text production" } ] }, "/transcription/all": { "get": { "tags": ["Speech to Text - Transcription"], "summary": "List All Transcriptions", "description": "Retrieve a paginated list of all audio and video transcription records created under your account.", "operationId": "listTranscriptions", "security": [ { "SttApiKey": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 10 } } ], "responses": { "200": { "description": "List of transcriptions retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "duration": { "type": "number" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "$ref": "#/components/responses/SttUnauthorized" } } }, "servers": [ { "url": "https://api.tunk.ai/v1", "description": "Speech-to-Text production" } ] }, "/transcription/{id}": { "get": { "tags": ["Speech to Text - Transcription"], "summary": "Get Transcription Detail", "description": "Retrieve complete details and results of an existing transcription job by its unique identifier.", "operationId": "getTranscriptionById", "security": [ { "SttApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Transcription job ID" } ], "responses": { "200": { "description": "Transcription details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "duration": { "type": "number" }, "file_url": { "type": "string" }, "text": { "type": "string" }, "segments": { "type": "array", "items": { "type": "object" } }, "summary": { "type": "string" }, "created_at": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/SttUnauthorized" }, "404": { "$ref": "#/components/responses/SttNotFound" } } }, "delete": { "tags": ["Speech to Text - Transcription"], "summary": "Delete Transcription", "description": "Permanently remove a transcription record and its associated text data.", "operationId": "deleteTranscription", "security": [ { "SttApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transcription deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Transcription deleted successfully" } } } } } }, "401": { "$ref": "#/components/responses/SttUnauthorized" }, "404": { "$ref": "#/components/responses/SttNotFound" } } }, "servers": [ { "url": "https://api.tunk.ai/v1", "description": "Speech-to-Text production" } ] } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Server-side API key. Bearer API keys are not accepted." }, "SttApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Speech-to-Text API key, sent directly without a Bearer prefix." } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": ["error"] }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" }, "statusCode": { "type": "integer" } } }, "CallCompletedEvent": { "type": "object", "required": ["id", "type", "created_at", "data"], "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable event ID; deduplicate by endpoint and this ID" }, "type": { "type": "string", "enum": ["call.completed"] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "session_id": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "call_status": { "type": "string", "nullable": true }, "to_phone_number": { "type": "string", "nullable": true }, "call_type": { "type": "string", "nullable": true }, "duration": { "type": "number", "nullable": true }, "call_sid": { "type": "string", "nullable": true }, "call_initiated_time": { "type": "string", "format": "date-time", "nullable": true }, "call_completed_time": { "type": "string", "format": "date-time", "nullable": true }, "call_terminated_by": { "type": "string", "nullable": true }, "transcript": { "description": "Stored transcript or null; representation depends on available call data" }, "recording": { "type": "object", "properties": { "url": { "type": "string", "nullable": true }, "expiry": { "type": "string", "format": "date-time", "nullable": true } } }, "analytics": { "type": "object", "properties": { "summary": { "type": "string", "nullable": true }, "sentiment": {}, "disposition": { "type": "string", "nullable": true }, "data_extraction": {} } } } } } }, "SttStandardError": { "type": "object", "properties": { "status": { "type": "integer" }, "message": { "type": "string" }, "error_code": { "type": "string", "nullable": true }, "request_id": { "type": "string", "nullable": true }, "details": { "type": "object", "nullable": true } } }, "CallDetail": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Unique session identifier for the call" }, "agent_id": { "type": "string", "format": "uuid", "description": "Agent UUID handling the conversation" }, "created_at": { "type": "string", "format": "date-time" }, "sentiment": { "type": "string", "nullable": true, "enum": ["positive", "neutral", "negative", null], "description": "Post-call AI sentiment classification" }, "disposition": { "type": "string", "nullable": true, "description": "Categorized call outcome tag" }, "summary": { "type": "string", "nullable": true, "description": "AI-generated executive conversation summary" }, "data_extraction": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Structured JSON entities extracted from dialogue" }, "transcript": { "type": "array", "nullable": true, "items": { "type": "object" }, "description": "Turn-by-turn dialogue transcript" }, "recording_url": { "type": "string", "nullable": true, "format": "uri", "description": "Pre-signed URL or S3 location of call audio recording" } } }, "CallSummaryItem": { "type": "object", "properties": { "session_id": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "call_status": { "type": "string", "nullable": true }, "duration": { "type": "number", "nullable": true }, "to_phone_number": { "type": "string", "nullable": true }, "call_type": { "type": "string", "nullable": true }, "disposition": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "responses": { "SttBadRequest": { "description": "Bad Request - Validation or parameter error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SttStandardError" }, "example": { "status": 400, "message": "Invalid recipient phone number format. Must be E.164.", "error_code": "INVALID_PHONE_NUMBER" } } } }, "SttUnauthorized": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SttStandardError" }, "example": { "status": 401, "message": "Invalid or missing API key in X-Api-Key header", "error_code": "UNAUTHORIZED" } } } }, "SttUnprocessableEntity": { "description": "Semantic validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SttStandardError" } } } }, "SttInternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SttStandardError" }, "example": { "status": 500, "message": "Internal server error encountered" } } } }, "SttNotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SttStandardError" }, "example": { "status": 404, "message": "The requested resource does not exist", "error_code": "NOT_FOUND" } } } } } } }