{ "openapi": "3.1.0", "info": { "title": "VoiceAgent Public API", "version": "0.0.1", "description": "Partner-facing REST API for managing VoiceAgent agents, calls, knowledge bases, phone numbers, webhooks, analytics, and post-call workflows. This preview contract is generated from the public OpenAPIHono route tree and is the reviewed artifact for Tier A public integrations. API key scopes (#42) are not yet enforced; documented surface intent is not yet the full technical reachability boundary.", "termsOfService": "https://voiceagent.example/terms", "contact": { "name": "VoiceAgent API Support", "email": "api-support@voiceagent.example", "url": "https://api-docs.voiceagent.example" }, "license": { "name": "Proprietary", "url": "https://voiceagent.example/legal/api-license" } }, "components": { "schemas": {}, "parameters": {}, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Use the `Bearer ` authorization header." }, "XApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Alternative API key header for environments where bearer authorization is hard to configure." } } }, "paths": { "/api/v1/agents": { "get": { "operationId": "agents.list", "x-api-key-required-scope": "agents:read", "x-api-key-risk-class": "standard", "x-route-id": "agents.list", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "number" }, "isPublished": { "type": "boolean" }, "versionDescription": { "type": ["string", "null"] }, "responseEngine": { "type": "object", "properties": { "type": { "type": "string", "enum": ["single_prompt", "conversation_flow", "custom_llm"] }, "prompt": { "type": "string" }, "model": { "type": "string" }, "llmWebsocketUrl": { "type": "string" } }, "required": ["type"], "additionalProperties": false }, "voiceId": { "type": "string" }, "voiceModel": { "type": ["string", "null"] }, "voiceTemperature": { "type": "number" }, "voiceSpeed": { "type": "number" }, "voiceEmotion": { "type": ["string", "null"], "enum": [ "calm", "sympathetic", "happy", "sad", "angry", "fearful", "surprised" ] }, "volume": { "type": "number" }, "enableDynamicVoiceSpeed": { "type": "boolean" }, "fallbackVoiceIds": { "type": "array", "items": { "type": "string" } }, "responsiveness": { "type": "number" }, "interruptionSensitivity": { "type": "number" }, "enableBackchannel": { "type": "boolean" }, "backchannelFrequency": { "type": "number" }, "backchannelWords": { "type": "array", "items": { "type": "string" } }, "reminderTriggerMs": { "type": "number" }, "reminderMaxCount": { "type": "number" }, "beginMessageDelayMs": { "type": "number" }, "beginMessage": { "type": ["string", "null"] }, "endCallAfterSilenceMs": { "type": "number" }, "maxCallDurationMs": { "type": "number" }, "language": { "type": "string" }, "sttMode": { "type": "string", "enum": ["fast", "accurate"] }, "sttProvider": { "type": "string" }, "ttsProvider": { "type": "string" }, "boostedKeywords": { "type": "array", "items": { "type": "string" } }, "adaptiveSpeechRate": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "minSpeed": { "type": "number" }, "maxSpeed": { "type": "number" }, "windowSize": { "type": "number" }, "speedRatio": { "type": "number" } }, "required": ["enabled", "minSpeed", "maxSpeed", "windowSize"], "additionalProperties": false }, "pronunciationDictionary": { "type": "array", "items": { "type": "object", "properties": { "find": { "type": "string" }, "replace": { "type": "string" }, "isRegex": { "type": "boolean" } }, "required": ["find", "replace"], "additionalProperties": false } }, "postCallAnalysisData": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": ["string", "enum", "boolean", "number"] }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } }, "required": ["name", "type", "description"], "additionalProperties": false } }, "postCallAnalysisModel": { "type": "string" }, "webhookUrl": { "type": ["string", "null"] }, "webhookEvents": { "type": "array", "items": { "type": "string" } }, "dataStorageSetting": { "type": "string", "enum": ["everything", "everything_except_pii", "basic_attributes_only"] }, "startSkillId": { "type": "string" }, "agentGlobalPrompt": { "type": "string" }, "agentVariables": { "type": "array", "items": {} }, "agentSettings": {}, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "version", "isPublished", "versionDescription", "responseEngine", "voiceId", "voiceModel", "voiceTemperature", "voiceSpeed", "voiceEmotion", "volume", "enableDynamicVoiceSpeed", "fallbackVoiceIds", "responsiveness", "interruptionSensitivity", "enableBackchannel", "backchannelFrequency", "backchannelWords", "reminderTriggerMs", "reminderMaxCount", "beginMessageDelayMs", "beginMessage", "endCallAfterSilenceMs", "maxCallDurationMs", "language", "sttMode", "sttProvider", "ttsProvider", "boostedKeywords", "postCallAnalysisData", "postCallAnalysisModel", "webhookUrl", "webhookEvents", "dataStorageSetting", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "agt_123", "name": "agents", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:read", "details": { "requiredScope": "agents:read", "routeId": "agents.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:read", "Agents"], "summary": "List agents", "description": "List agents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:read`. Risk class: `standard`. Route ID: `agents.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "post": { "operationId": "agents.create", "x-api-key-required-scope": "agents:write", "x-api-key-risk-class": "standard", "x-route-id": "agents.create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "voiceId": { "type": "string", "minLength": 1 }, "responseEngineType": { "type": "string", "enum": ["single_prompt", "conversation_flow", "custom_llm"], "default": "conversation_flow" }, "prompt": { "type": "string" }, "llmModel": { "type": "string", "default": "gpt-5.4-mini" }, "language": { "type": "string", "default": "ja" }, "beginMessage": { "type": "string" }, "adaptiveSpeechRate": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "minSpeed": { "type": "number", "minimum": 0.5, "maximum": 1 }, "maxSpeed": { "type": "number", "minimum": 1, "maximum": 2 }, "windowSize": { "type": "integer", "minimum": 1, "maximum": 10 }, "speedRatio": { "type": "number", "minimum": 0.5, "maximum": 2 } }, "required": ["enabled", "minSpeed", "maxSpeed", "windowSize"] } }, "required": ["name", "voiceId"] }, "examples": { "default": { "summary": "Create agents request", "value": { "name": "Support concierge", "voiceId": "voice_ja_female_01", "responseEngineType": "conversation_flow", "prompt": "Help callers book appointments and answer policy questions.", "llmModel": "gpt-5.4-mini", "language": "ja" } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "number" }, "isPublished": { "type": "boolean" }, "versionDescription": { "type": ["string", "null"] }, "responseEngine": { "type": "object", "properties": { "type": { "type": "string", "enum": ["single_prompt", "conversation_flow", "custom_llm"] }, "prompt": { "type": "string" }, "model": { "type": "string" }, "llmWebsocketUrl": { "type": "string" } }, "required": ["type"], "additionalProperties": false }, "voiceId": { "type": "string" }, "voiceModel": { "type": ["string", "null"] }, "voiceTemperature": { "type": "number" }, "voiceSpeed": { "type": "number" }, "voiceEmotion": { "type": ["string", "null"], "enum": [ "calm", "sympathetic", "happy", "sad", "angry", "fearful", "surprised" ] }, "volume": { "type": "number" }, "enableDynamicVoiceSpeed": { "type": "boolean" }, "fallbackVoiceIds": { "type": "array", "items": { "type": "string" } }, "responsiveness": { "type": "number" }, "interruptionSensitivity": { "type": "number" }, "enableBackchannel": { "type": "boolean" }, "backchannelFrequency": { "type": "number" }, "backchannelWords": { "type": "array", "items": { "type": "string" } }, "reminderTriggerMs": { "type": "number" }, "reminderMaxCount": { "type": "number" }, "beginMessageDelayMs": { "type": "number" }, "beginMessage": { "type": ["string", "null"] }, "endCallAfterSilenceMs": { "type": "number" }, "maxCallDurationMs": { "type": "number" }, "language": { "type": "string" }, "sttMode": { "type": "string", "enum": ["fast", "accurate"] }, "sttProvider": { "type": "string" }, "ttsProvider": { "type": "string" }, "boostedKeywords": { "type": "array", "items": { "type": "string" } }, "adaptiveSpeechRate": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "minSpeed": { "type": "number" }, "maxSpeed": { "type": "number" }, "windowSize": { "type": "number" }, "speedRatio": { "type": "number" } }, "required": ["enabled", "minSpeed", "maxSpeed", "windowSize"], "additionalProperties": false }, "pronunciationDictionary": { "type": "array", "items": { "type": "object", "properties": { "find": { "type": "string" }, "replace": { "type": "string" }, "isRegex": { "type": "boolean" } }, "required": ["find", "replace"], "additionalProperties": false } }, "postCallAnalysisData": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": ["string", "enum", "boolean", "number"] }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } }, "required": ["name", "type", "description"], "additionalProperties": false } }, "postCallAnalysisModel": { "type": "string" }, "webhookUrl": { "type": ["string", "null"] }, "webhookEvents": { "type": "array", "items": { "type": "string" } }, "dataStorageSetting": { "type": "string", "enum": ["everything", "everything_except_pii", "basic_attributes_only"] }, "startSkillId": { "type": "string" }, "agentGlobalPrompt": { "type": "string" }, "agentVariables": { "type": "array", "items": {} }, "agentSettings": {}, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "version", "isPublished", "versionDescription", "responseEngine", "voiceId", "voiceModel", "voiceTemperature", "voiceSpeed", "voiceEmotion", "volume", "enableDynamicVoiceSpeed", "fallbackVoiceIds", "responsiveness", "interruptionSensitivity", "enableBackchannel", "backchannelFrequency", "backchannelWords", "reminderTriggerMs", "reminderMaxCount", "beginMessageDelayMs", "beginMessage", "endCallAfterSilenceMs", "maxCallDurationMs", "language", "sttMode", "sttProvider", "ttsProvider", "boostedKeywords", "postCallAnalysisData", "postCallAnalysisModel", "webhookUrl", "webhookEvents", "dataStorageSetting", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "agt_123", "name": "agents", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:write", "details": { "requiredScope": "agents:write", "routeId": "agents.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:write", "Agents"], "summary": "Create agents", "description": "Create agents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:write`. Risk class: `standard`. Route ID: `agents.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/agents\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{id}": { "get": { "operationId": "agents.get", "x-api-key-required-scope": "agents:read", "x-api-key-risk-class": "standard", "x-route-id": "agents.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "number" }, "isPublished": { "type": "boolean" }, "versionDescription": { "type": ["string", "null"] }, "responseEngine": { "type": "object", "properties": { "type": { "type": "string", "enum": ["single_prompt", "conversation_flow", "custom_llm"] }, "prompt": { "type": "string" }, "model": { "type": "string" }, "llmWebsocketUrl": { "type": "string" } }, "required": ["type"], "additionalProperties": false }, "voiceId": { "type": "string" }, "voiceModel": { "type": ["string", "null"] }, "voiceTemperature": { "type": "number" }, "voiceSpeed": { "type": "number" }, "voiceEmotion": { "type": ["string", "null"], "enum": [ "calm", "sympathetic", "happy", "sad", "angry", "fearful", "surprised" ] }, "volume": { "type": "number" }, "enableDynamicVoiceSpeed": { "type": "boolean" }, "fallbackVoiceIds": { "type": "array", "items": { "type": "string" } }, "responsiveness": { "type": "number" }, "interruptionSensitivity": { "type": "number" }, "enableBackchannel": { "type": "boolean" }, "backchannelFrequency": { "type": "number" }, "backchannelWords": { "type": "array", "items": { "type": "string" } }, "reminderTriggerMs": { "type": "number" }, "reminderMaxCount": { "type": "number" }, "beginMessageDelayMs": { "type": "number" }, "beginMessage": { "type": ["string", "null"] }, "endCallAfterSilenceMs": { "type": "number" }, "maxCallDurationMs": { "type": "number" }, "language": { "type": "string" }, "sttMode": { "type": "string", "enum": ["fast", "accurate"] }, "sttProvider": { "type": "string" }, "ttsProvider": { "type": "string" }, "boostedKeywords": { "type": "array", "items": { "type": "string" } }, "adaptiveSpeechRate": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "minSpeed": { "type": "number" }, "maxSpeed": { "type": "number" }, "windowSize": { "type": "number" }, "speedRatio": { "type": "number" } }, "required": ["enabled", "minSpeed", "maxSpeed", "windowSize"], "additionalProperties": false }, "pronunciationDictionary": { "type": "array", "items": { "type": "object", "properties": { "find": { "type": "string" }, "replace": { "type": "string" }, "isRegex": { "type": "boolean" } }, "required": ["find", "replace"], "additionalProperties": false } }, "postCallAnalysisData": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": ["string", "enum", "boolean", "number"] }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } }, "required": ["name", "type", "description"], "additionalProperties": false } }, "postCallAnalysisModel": { "type": "string" }, "webhookUrl": { "type": ["string", "null"] }, "webhookEvents": { "type": "array", "items": { "type": "string" } }, "dataStorageSetting": { "type": "string", "enum": ["everything", "everything_except_pii", "basic_attributes_only"] }, "startSkillId": { "type": "string" }, "agentGlobalPrompt": { "type": "string" }, "agentVariables": { "type": "array", "items": {} }, "agentSettings": {}, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "version", "isPublished", "versionDescription", "responseEngine", "voiceId", "voiceModel", "voiceTemperature", "voiceSpeed", "voiceEmotion", "volume", "enableDynamicVoiceSpeed", "fallbackVoiceIds", "responsiveness", "interruptionSensitivity", "enableBackchannel", "backchannelFrequency", "backchannelWords", "reminderTriggerMs", "reminderMaxCount", "beginMessageDelayMs", "beginMessage", "endCallAfterSilenceMs", "maxCallDurationMs", "language", "sttMode", "sttProvider", "ttsProvider", "boostedKeywords", "postCallAnalysisData", "postCallAnalysisModel", "webhookUrl", "webhookEvents", "dataStorageSetting", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "agt_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:read", "details": { "requiredScope": "agents:read", "routeId": "agents.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:read", "Agents"], "summary": "Get agents", "description": "Get agents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:read`. Risk class: `standard`. Route ID: `agents.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/kb_123?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "patch": { "operationId": "agents.update", "x-api-key-required-scope": "agents:write", "x-api-key-risk-class": "standard", "x-route-id": "agents.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "voiceId": { "type": "string", "minLength": 1 }, "voiceModel": { "type": ["string", "null"] }, "responseEngineType": { "type": "string", "enum": ["single_prompt", "conversation_flow", "custom_llm"] }, "prompt": { "type": "string" }, "llmModel": { "type": "string" }, "voiceTemperature": { "type": "number", "minimum": 0, "maximum": 2 }, "voiceSpeed": { "type": "number", "minimum": 0.5, "maximum": 2 }, "voiceEmotion": { "type": ["string", "null"], "enum": ["calm", "sympathetic", "happy", "sad", "angry", "fearful", "surprised"] }, "volume": { "type": "number", "minimum": 0, "maximum": 2 }, "responsiveness": { "type": "number", "minimum": 0, "maximum": 1 }, "interruptionSensitivity": { "type": "number", "minimum": 0, "maximum": 1 }, "enableBackchannel": { "type": "boolean" }, "backchannelFrequency": { "type": "number", "minimum": 0, "maximum": 1 }, "backchannelWords": { "type": "array", "items": { "type": "string" } }, "language": { "type": "string" }, "sttMode": { "type": "string", "enum": ["fast", "accurate"] }, "sttProvider": { "type": "string" }, "ttsProvider": { "type": "string" }, "beginMessage": { "type": ["string", "null"] }, "endCallAfterSilenceMs": { "type": "number", "minimum": 10000 }, "maxCallDurationMs": { "type": "number", "minimum": 60000, "maximum": 7200000 }, "boostedKeywords": { "type": "array", "items": { "type": "string" } }, "dataStorageSetting": { "type": "string", "enum": ["everything", "everything_except_pii", "basic_attributes_only"] }, "reminderTriggerMs": { "type": "number", "minimum": 0, "maximum": 60000 }, "reminderMaxCount": { "type": "number", "minimum": 0, "maximum": 10 }, "beginMessageDelayMs": { "type": "number", "minimum": 0, "maximum": 10000 }, "postCallAnalysisData": { "type": "array", "items": {} }, "pronunciationDictionary": { "type": "array", "items": { "type": "object", "properties": { "find": { "type": "string", "minLength": 1 }, "replace": { "type": "string" }, "isRegex": { "type": "boolean" } }, "required": ["find", "replace"] } }, "adaptiveSpeechRate": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "minSpeed": { "type": "number", "minimum": 0.5, "maximum": 1 }, "maxSpeed": { "type": "number", "minimum": 1, "maximum": 2 }, "windowSize": { "type": "integer", "minimum": 1, "maximum": 10 }, "speedRatio": { "type": "number", "minimum": 0.5, "maximum": 2 } }, "required": ["enabled", "minSpeed", "maxSpeed", "windowSize"] }, "kbConfig": { "type": "object", "properties": { "topK": { "type": "integer", "minimum": 1, "maximum": 20 }, "filterScore": { "type": "number", "minimum": 0, "maximum": 1 }, "searchMode": { "type": "string", "enum": ["lexical", "vector", "hybrid"] }, "semanticRatio": { "type": "number", "minimum": 0, "maximum": 1 }, "queryExpansion": { "type": "object", "properties": { "gqr": { "type": "boolean" }, "contextWindow": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": ["gqr", "contextWindow"] } }, "required": ["topK", "filterScore"] }, "startSkillId": { "type": "string" }, "agentSettings": { "type": "object", "additionalProperties": {} }, "agentGlobalPrompt": { "type": "string" }, "agentVariables": { "type": "array", "items": {} } } }, "examples": { "default": { "summary": "Update agents request", "value": { "name": "Partner support", "voiceId": "voice_123", "voiceModel": "gpt-5.4-mini", "responseEngineType": "single_prompt" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "number" }, "isPublished": { "type": "boolean" }, "versionDescription": { "type": ["string", "null"] }, "responseEngine": { "type": "object", "properties": { "type": { "type": "string", "enum": ["single_prompt", "conversation_flow", "custom_llm"] }, "prompt": { "type": "string" }, "model": { "type": "string" }, "llmWebsocketUrl": { "type": "string" } }, "required": ["type"], "additionalProperties": false }, "voiceId": { "type": "string" }, "voiceModel": { "type": ["string", "null"] }, "voiceTemperature": { "type": "number" }, "voiceSpeed": { "type": "number" }, "voiceEmotion": { "type": ["string", "null"], "enum": [ "calm", "sympathetic", "happy", "sad", "angry", "fearful", "surprised" ] }, "volume": { "type": "number" }, "enableDynamicVoiceSpeed": { "type": "boolean" }, "fallbackVoiceIds": { "type": "array", "items": { "type": "string" } }, "responsiveness": { "type": "number" }, "interruptionSensitivity": { "type": "number" }, "enableBackchannel": { "type": "boolean" }, "backchannelFrequency": { "type": "number" }, "backchannelWords": { "type": "array", "items": { "type": "string" } }, "reminderTriggerMs": { "type": "number" }, "reminderMaxCount": { "type": "number" }, "beginMessageDelayMs": { "type": "number" }, "beginMessage": { "type": ["string", "null"] }, "endCallAfterSilenceMs": { "type": "number" }, "maxCallDurationMs": { "type": "number" }, "language": { "type": "string" }, "sttMode": { "type": "string", "enum": ["fast", "accurate"] }, "sttProvider": { "type": "string" }, "ttsProvider": { "type": "string" }, "boostedKeywords": { "type": "array", "items": { "type": "string" } }, "adaptiveSpeechRate": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "minSpeed": { "type": "number" }, "maxSpeed": { "type": "number" }, "windowSize": { "type": "number" }, "speedRatio": { "type": "number" } }, "required": ["enabled", "minSpeed", "maxSpeed", "windowSize"], "additionalProperties": false }, "pronunciationDictionary": { "type": "array", "items": { "type": "object", "properties": { "find": { "type": "string" }, "replace": { "type": "string" }, "isRegex": { "type": "boolean" } }, "required": ["find", "replace"], "additionalProperties": false } }, "postCallAnalysisData": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": ["string", "enum", "boolean", "number"] }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } }, "required": ["name", "type", "description"], "additionalProperties": false } }, "postCallAnalysisModel": { "type": "string" }, "webhookUrl": { "type": ["string", "null"] }, "webhookEvents": { "type": "array", "items": { "type": "string" } }, "dataStorageSetting": { "type": "string", "enum": ["everything", "everything_except_pii", "basic_attributes_only"] }, "startSkillId": { "type": "string" }, "agentGlobalPrompt": { "type": "string" }, "agentVariables": { "type": "array", "items": {} }, "agentSettings": {}, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "version", "isPublished", "versionDescription", "responseEngine", "voiceId", "voiceModel", "voiceTemperature", "voiceSpeed", "voiceEmotion", "volume", "enableDynamicVoiceSpeed", "fallbackVoiceIds", "responsiveness", "interruptionSensitivity", "enableBackchannel", "backchannelFrequency", "backchannelWords", "reminderTriggerMs", "reminderMaxCount", "beginMessageDelayMs", "beginMessage", "endCallAfterSilenceMs", "maxCallDurationMs", "language", "sttMode", "sttProvider", "ttsProvider", "boostedKeywords", "postCallAnalysisData", "postCallAnalysisModel", "webhookUrl", "webhookEvents", "dataStorageSetting", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "agt_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:write", "details": { "requiredScope": "agents:write", "routeId": "agents.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:write", "Agents"], "summary": "Update agents", "description": "Update agents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:write`. Risk class: `standard`. Route ID: `agents.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/agents/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "agents.delete", "x-api-key-required-scope": "agents:write", "x-api-key-risk-class": "standard", "x-route-id": "agents.delete", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:write", "details": { "requiredScope": "agents:write", "routeId": "agents.delete" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:write", "Agents"], "summary": "Delete agents", "description": "Delete agents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:write`. Risk class: `standard`. Route ID: `agents.delete`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/agents/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{id}/publish": { "post": { "operationId": "agents.publish", "x-api-key-required-scope": "agents:admin", "x-api-key-risk-class": "standard", "x-route-id": "agents.publish", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" } } }, "examples": { "default": { "summary": "Publish agent request", "value": { "description": "Used by the partner integration." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "number" }, "isPublished": { "type": "boolean" }, "versionDescription": { "type": ["string", "null"] }, "responseEngine": { "type": "object", "properties": { "type": { "type": "string", "enum": ["single_prompt", "conversation_flow", "custom_llm"] }, "prompt": { "type": "string" }, "model": { "type": "string" }, "llmWebsocketUrl": { "type": "string" } }, "required": ["type"], "additionalProperties": false }, "voiceId": { "type": "string" }, "voiceModel": { "type": ["string", "null"] }, "voiceTemperature": { "type": "number" }, "voiceSpeed": { "type": "number" }, "voiceEmotion": { "type": ["string", "null"], "enum": [ "calm", "sympathetic", "happy", "sad", "angry", "fearful", "surprised" ] }, "volume": { "type": "number" }, "enableDynamicVoiceSpeed": { "type": "boolean" }, "fallbackVoiceIds": { "type": "array", "items": { "type": "string" } }, "responsiveness": { "type": "number" }, "interruptionSensitivity": { "type": "number" }, "enableBackchannel": { "type": "boolean" }, "backchannelFrequency": { "type": "number" }, "backchannelWords": { "type": "array", "items": { "type": "string" } }, "reminderTriggerMs": { "type": "number" }, "reminderMaxCount": { "type": "number" }, "beginMessageDelayMs": { "type": "number" }, "beginMessage": { "type": ["string", "null"] }, "endCallAfterSilenceMs": { "type": "number" }, "maxCallDurationMs": { "type": "number" }, "language": { "type": "string" }, "sttMode": { "type": "string", "enum": ["fast", "accurate"] }, "sttProvider": { "type": "string" }, "ttsProvider": { "type": "string" }, "boostedKeywords": { "type": "array", "items": { "type": "string" } }, "adaptiveSpeechRate": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "minSpeed": { "type": "number" }, "maxSpeed": { "type": "number" }, "windowSize": { "type": "number" }, "speedRatio": { "type": "number" } }, "required": ["enabled", "minSpeed", "maxSpeed", "windowSize"], "additionalProperties": false }, "pronunciationDictionary": { "type": "array", "items": { "type": "object", "properties": { "find": { "type": "string" }, "replace": { "type": "string" }, "isRegex": { "type": "boolean" } }, "required": ["find", "replace"], "additionalProperties": false } }, "postCallAnalysisData": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": ["string", "enum", "boolean", "number"] }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } }, "required": ["name", "type", "description"], "additionalProperties": false } }, "postCallAnalysisModel": { "type": "string" }, "webhookUrl": { "type": ["string", "null"] }, "webhookEvents": { "type": "array", "items": { "type": "string" } }, "dataStorageSetting": { "type": "string", "enum": ["everything", "everything_except_pii", "basic_attributes_only"] }, "startSkillId": { "type": "string" }, "agentGlobalPrompt": { "type": "string" }, "agentVariables": { "type": "array", "items": {} }, "agentSettings": {}, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "version", "isPublished", "versionDescription", "responseEngine", "voiceId", "voiceModel", "voiceTemperature", "voiceSpeed", "voiceEmotion", "volume", "enableDynamicVoiceSpeed", "fallbackVoiceIds", "responsiveness", "interruptionSensitivity", "enableBackchannel", "backchannelFrequency", "backchannelWords", "reminderTriggerMs", "reminderMaxCount", "beginMessageDelayMs", "beginMessage", "endCallAfterSilenceMs", "maxCallDurationMs", "language", "sttMode", "sttProvider", "ttsProvider", "boostedKeywords", "postCallAnalysisData", "postCallAnalysisModel", "webhookUrl", "webhookEvents", "dataStorageSetting", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "agt_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:admin", "details": { "requiredScope": "agents:admin", "routeId": "agents.publish" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:admin", "Agents"], "summary": "Publish agent", "description": "Publish agent.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:admin`. Risk class: `standard`. Route ID: `agents.publish`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/agents/kb_123/publish\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{id}/knowledge-bases": { "get": { "operationId": "agents.listKnowledgeBases", "x-api-key-required-scope": "agents:read", "x-api-key-risk-class": "standard", "x-route-id": "agents.listKnowledgeBases", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "documentCount": { "type": "number" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "chunkConfig": { "type": "object", "properties": { "maxChunkChars": { "type": "number" }, "minChunkChars": { "type": "number" }, "overlapSentences": { "type": "number" }, "splitThreshold": { "type": "number" } }, "additionalProperties": false }, "contentVersion": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "description", "documentCount", "status", "chunkConfig", "contentVersion", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "kb_123", "name": "knowledge bases", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:read", "details": { "requiredScope": "agents:read", "routeId": "agents.listKnowledgeBases" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:read", "Agent Knowledge"], "summary": "Get knowledge bases", "description": "Get knowledge bases.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:read`. Risk class: `standard`. Route ID: `agents.listKnowledgeBases`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/kb_123/knowledge-bases?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "put": { "operationId": "agents.replaceKnowledgeBases", "x-api-key-required-scope": "agents:write", "x-api-key-risk-class": "standard", "x-route-id": "agents.replaceKnowledgeBases", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "knowledgeBaseIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": ["knowledgeBaseIds"] }, "examples": { "default": { "summary": "Replace knowledge bases request", "value": { "knowledgeBaseIds": ["11111111-1111-4111-8111-111111111111"] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:write", "details": { "requiredScope": "agents:write", "routeId": "agents.replaceKnowledgeBases" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:write", "Agent Knowledge"], "summary": "Replace knowledge bases", "description": "Replace knowledge bases.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:write`. Risk class: `standard`. Route ID: `agents.replaceKnowledgeBases`.\n\nExample:\n\n```sh\ncurl -sS -X PUT \"https://api.voiceagent.example/api/v1/agents/kb_123/knowledge-bases\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/kb-overview": { "get": { "operationId": "agentKnowledgeOverview.get", "x-api-key-required-scope": "agents:read", "x-api-key-risk-class": "standard", "x-route-id": "agentKnowledgeOverview.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string" }, "agentName": { "type": "string" }, "workspaceDefaults": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "source": { "type": "string", "enum": ["workspace", "agent", "skill", "node"] } }, "required": ["id", "name", "status", "source"], "additionalProperties": false } }, "agentBindings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "source": { "type": "string", "enum": ["workspace", "agent", "skill", "node"] } }, "required": ["id", "name", "status", "source"], "additionalProperties": false } }, "skills": { "type": "array", "items": { "type": "object", "properties": { "skillId": { "type": "string" }, "skillName": { "type": "string" }, "effectiveKbs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "source": { "type": "string", "enum": ["workspace", "agent", "skill", "node"] } }, "required": ["id", "name", "status", "source"], "additionalProperties": false } }, "kbConfigOverride": { "type": ["object", "null"], "properties": { "topK": { "type": ["number", "null"] }, "filterScore": { "type": ["number", "null"] }, "searchMode": { "type": ["string", "null"] }, "semanticRatio": { "type": ["number", "null"] }, "gqrEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "null" } ] }, "contextWindow": { "type": ["number", "null"] } }, "additionalProperties": false }, "nodeOverrideCount": { "type": "number" } }, "required": [ "skillId", "skillName", "effectiveKbs", "kbConfigOverride", "nodeOverrideCount" ], "additionalProperties": false } } }, "required": [ "agentId", "agentName", "workspaceDefaults", "agentBindings", "skills" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "kb_123", "name": "knowledge overview", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:read", "details": { "requiredScope": "agents:read", "routeId": "agentKnowledgeOverview.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:read", "Agent Knowledge"], "summary": "Get knowledge overview", "description": "Get knowledge overview.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:read`. Risk class: `standard`. Route ID: `agentKnowledgeOverview.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/agt_123/kb-overview?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/webhooks": { "get": { "operationId": "agentWebhooks.list", "x-api-key-required-scope": "webhooks:read", "x-api-key-risk-class": "standard", "x-route-id": "agentWebhooks.list", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "call.started", "call.ended", "call.analyzed", "agent.updated", "phone_number.created", "phone_number.deleted" ] } }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "agentId": { "type": "string" } }, "required": [ "id", "workspaceId", "url", "events", "customHeaders", "isActive", "createdAt", "updatedAt", "agentId" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "wh_123", "name": "webhooks", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: webhooks:read", "details": { "requiredScope": "webhooks:read", "routeId": "agentWebhooks.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: webhooks:read", "Agent Webhooks"], "summary": "Get webhooks", "description": "Get webhooks.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `webhooks:read`. Risk class: `standard`. Route ID: `agentWebhooks.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/agt_123/webhooks?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "post": { "operationId": "agentWebhooks.create", "x-api-key-required-scope": "webhooks:write", "x-api-key-risk-class": "high", "x-route-id": "agentWebhooks.create", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "call.started", "call.ended", "call.analyzed", "agent.updated", "phone_number.created", "phone_number.deleted" ] }, "minItems": 1 }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": ["url", "events"] }, "examples": { "default": { "summary": "Create webhooks request", "value": { "url": "https://partner.example/webhooks/voiceagent", "events": ["call.started", "call.ended"], "customHeaders": { "X-Partner-Tenant": "tokyo" } } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "call.started", "call.ended", "call.analyzed", "agent.updated", "phone_number.created", "phone_number.deleted" ] } }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "agentId": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "workspaceId", "url", "events", "customHeaders", "isActive", "createdAt", "updatedAt", "agentId", "secret" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "wh_123", "name": "webhooks", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: webhooks:write", "details": { "requiredScope": "webhooks:write", "routeId": "agentWebhooks.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: webhooks:write", "Agent Webhooks"], "summary": "Create webhooks", "description": "Create webhooks.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `webhooks:write`. Risk class: `high`. Route ID: `agentWebhooks.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/agents/agt_123/webhooks\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/webhooks/{id}": { "patch": { "operationId": "agentWebhooks.update", "x-api-key-required-scope": "webhooks:write", "x-api-key-risk-class": "high", "x-route-id": "agentWebhooks.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "call.started", "call.ended", "call.analyzed", "agent.updated", "phone_number.created", "phone_number.deleted" ] }, "minItems": 1 }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } }, "isActive": { "type": "boolean" } } }, "examples": { "default": { "summary": "Update webhooks request", "value": { "url": "https://partner.example/webhooks/voiceagent", "events": ["call.started", "call.ended"], "customHeaders": { "X-Partner-Tenant": "tokyo" } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "call.started", "call.ended", "call.analyzed", "agent.updated", "phone_number.created", "phone_number.deleted" ] } }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "agentId": { "type": "string" } }, "required": [ "id", "workspaceId", "url", "events", "customHeaders", "isActive", "createdAt", "updatedAt", "agentId" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "wh_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: webhooks:write", "details": { "requiredScope": "webhooks:write", "routeId": "agentWebhooks.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: webhooks:write", "Agent Webhooks"], "summary": "Update webhooks", "description": "Update webhooks.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `webhooks:write`. Risk class: `high`. Route ID: `agentWebhooks.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/agents/agt_123/webhooks/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "agentWebhooks.delete", "x-api-key-required-scope": "webhooks:write", "x-api-key-risk-class": "high", "x-route-id": "agentWebhooks.delete", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: webhooks:write", "details": { "requiredScope": "webhooks:write", "routeId": "agentWebhooks.delete" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: webhooks:write", "Agent Webhooks"], "summary": "Delete webhooks", "description": "Delete webhooks.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `webhooks:write`. Risk class: `high`. Route ID: `agentWebhooks.delete`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/agents/agt_123/webhooks/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/webhooks/{id}/test": { "post": { "operationId": "agentWebhooks.test", "x-api-key-required-scope": "webhooks:execute", "x-api-key-risk-class": "standard", "x-route-id": "agentWebhooks.test", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": ["number", "null"] }, "durationMs": { "type": "number" }, "responseBody": { "type": ["string", "null"] } }, "required": ["statusCode", "durationMs", "responseBody"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "wh_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: webhooks:execute", "details": { "requiredScope": "webhooks:execute", "routeId": "agentWebhooks.test" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: webhooks:execute", "Agent Webhooks"], "summary": "Test webhooks", "description": "Test webhooks.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `webhooks:execute`. Risk class: `standard`. Route ID: `agentWebhooks.test`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/agents/agt_123/webhooks/kb_123/test\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/skills": { "post": { "operationId": "skills.create", "x-api-key-required-scope": "agents:write", "x-api-key-risk-class": "standard", "x-route-id": "skills.create", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "skillType": { "type": "string", "enum": ["conversation_flow"], "default": "conversation_flow" }, "description": { "type": "string" }, "startNodeId": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "skillPrompt": { "type": "string" }, "skillVariables": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "globalNodes": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "settings": { "type": "object", "additionalProperties": {} }, "searchProfile": { "type": "object", "additionalProperties": {} }, "entitySearchSources": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "sortOrder": { "type": "integer" } }, "required": ["name"] }, "examples": { "default": { "summary": "Create skills request", "value": { "name": "Partner support", "skillType": "conversation_flow", "description": "Used by the partner integration.", "startNodeId": "startNode_123", "nodes": [ { "key": "value" } ] } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "skillType": { "type": "string", "enum": ["conversation_flow"] }, "description": { "type": ["string", "null"] }, "startNodeId": { "type": ["string", "null"] }, "nodes": { "type": "array", "items": {} }, "skillPrompt": { "type": ["string", "null"] }, "skillVariables": { "type": ["array", "null"], "items": {} }, "globalNodes": { "type": ["array", "null"], "items": {} }, "settings": { "type": "object", "additionalProperties": true }, "searchProfile": { "type": "object", "additionalProperties": true }, "entitySearchSources": { "type": ["array", "null"], "items": {} }, "sortOrder": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "workspaceId", "name", "skillType", "description", "startNodeId", "nodes", "skillPrompt", "skillVariables", "globalNodes", "settings", "searchProfile", "entitySearchSources", "sortOrder", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "skill_123", "name": "skills", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:write", "details": { "requiredScope": "agents:write", "routeId": "skills.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:write", "Skills"], "summary": "Create skills", "description": "Create skills.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:write`. Risk class: `standard`. Route ID: `skills.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/agents/agt_123/skills\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "get": { "operationId": "skills.list", "x-api-key-required-scope": "agents:read", "x-api-key-risk-class": "standard", "x-route-id": "skills.list", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "skillType": { "type": "string", "enum": ["conversation_flow"] }, "description": { "type": ["string", "null"] }, "startNodeId": { "type": ["string", "null"] }, "nodes": { "type": "array", "items": {} }, "skillPrompt": { "type": ["string", "null"] }, "skillVariables": { "type": ["array", "null"], "items": {} }, "globalNodes": { "type": ["array", "null"], "items": {} }, "settings": { "type": "object", "additionalProperties": true }, "searchProfile": { "type": "object", "additionalProperties": true }, "entitySearchSources": { "type": ["array", "null"], "items": {} }, "sortOrder": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "workspaceId", "name", "skillType", "description", "startNodeId", "nodes", "skillPrompt", "skillVariables", "globalNodes", "settings", "searchProfile", "entitySearchSources", "sortOrder", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "skill_123", "name": "skills", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:read", "details": { "requiredScope": "agents:read", "routeId": "skills.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:read", "Skills"], "summary": "Get skills", "description": "Get skills.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:read`. Risk class: `standard`. Route ID: `skills.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/agt_123/skills?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/skills/{skillId}": { "get": { "operationId": "skills.get", "x-api-key-required-scope": "agents:read", "x-api-key-risk-class": "standard", "x-route-id": "skills.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "skillId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "skillType": { "type": "string", "enum": ["conversation_flow"] }, "description": { "type": ["string", "null"] }, "startNodeId": { "type": ["string", "null"] }, "nodes": { "type": "array", "items": {} }, "skillPrompt": { "type": ["string", "null"] }, "skillVariables": { "type": ["array", "null"], "items": {} }, "globalNodes": { "type": ["array", "null"], "items": {} }, "settings": { "type": "object", "additionalProperties": true }, "searchProfile": { "type": "object", "additionalProperties": true }, "entitySearchSources": { "type": ["array", "null"], "items": {} }, "sortOrder": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "workspaceId", "name", "skillType", "description", "startNodeId", "nodes", "skillPrompt", "skillVariables", "globalNodes", "settings", "searchProfile", "entitySearchSources", "sortOrder", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "skill_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:read", "details": { "requiredScope": "agents:read", "routeId": "skills.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:read", "Skills"], "summary": "Get skills", "description": "Get skills.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:read`. Risk class: `standard`. Route ID: `skills.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "patch": { "operationId": "skills.update", "x-api-key-required-scope": "agents:write", "x-api-key-risk-class": "standard", "x-route-id": "skills.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "skillId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "startNodeId": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "skillPrompt": { "type": "string" }, "skillVariables": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "globalNodes": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "settings": { "type": "object", "additionalProperties": {} }, "searchProfile": { "type": "object", "additionalProperties": {} }, "entitySearchSources": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "sortOrder": { "type": "integer" } } }, "examples": { "default": { "summary": "Update skills request", "value": { "name": "Partner support", "description": "Used by the partner integration.", "startNodeId": "startNode_123", "nodes": [ { "key": "value" } ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "skillType": { "type": "string", "enum": ["conversation_flow"] }, "description": { "type": ["string", "null"] }, "startNodeId": { "type": ["string", "null"] }, "nodes": { "type": "array", "items": {} }, "skillPrompt": { "type": ["string", "null"] }, "skillVariables": { "type": ["array", "null"], "items": {} }, "globalNodes": { "type": ["array", "null"], "items": {} }, "settings": { "type": "object", "additionalProperties": true }, "searchProfile": { "type": "object", "additionalProperties": true }, "entitySearchSources": { "type": ["array", "null"], "items": {} }, "sortOrder": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "workspaceId", "name", "skillType", "description", "startNodeId", "nodes", "skillPrompt", "skillVariables", "globalNodes", "settings", "searchProfile", "entitySearchSources", "sortOrder", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "skill_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:write", "details": { "requiredScope": "agents:write", "routeId": "skills.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:write", "Skills"], "summary": "Update skills", "description": "Update skills.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:write`. Risk class: `standard`. Route ID: `skills.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "skills.delete", "x-api-key-required-scope": "agents:write", "x-api-key-risk-class": "standard", "x-route-id": "skills.delete", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "skillId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:write", "details": { "requiredScope": "agents:write", "routeId": "skills.delete" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:write", "Skills"], "summary": "Delete skills", "description": "Delete skills.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:write`. Risk class: `standard`. Route ID: `skills.delete`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/skills/{skillId}/knowledge-bases": { "get": { "operationId": "skillKnowledgeBases.list", "x-api-key-required-scope": "agents:read", "x-api-key-risk-class": "standard", "x-route-id": "skillKnowledgeBases.list", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "skillId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "effective": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": ["workspace", "agent", "skill", "node"] } }, "required": ["id", "name", "source"], "additionalProperties": false } }, "inherited": { "type": "object", "properties": { "workspace": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": ["workspace", "agent", "skill", "node"] } }, "required": ["id", "name", "source"], "additionalProperties": false } }, "agent": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": ["workspace", "agent", "skill", "node"] } }, "required": ["id", "name", "source"], "additionalProperties": false } } }, "required": ["workspace", "agent"], "additionalProperties": false }, "skillOverride": { "type": "array", "items": { "type": "string" } } }, "required": ["effective", "inherited", "skillOverride"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "kb_123", "name": "knowledge bases", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:read", "details": { "requiredScope": "agents:read", "routeId": "skillKnowledgeBases.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:read", "Agent Knowledge"], "summary": "Get knowledge bases", "description": "Get knowledge bases.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:read`. Risk class: `standard`. Route ID: `skillKnowledgeBases.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123/knowledge-bases?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "put": { "operationId": "skillKnowledgeBases.replace", "x-api-key-required-scope": "agents:write", "x-api-key-risk-class": "standard", "x-route-id": "skillKnowledgeBases.replace", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "skillId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "knowledgeBaseIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": ["knowledgeBaseIds"] }, "examples": { "default": { "summary": "Replace knowledge bases request", "value": { "knowledgeBaseIds": ["11111111-1111-4111-8111-111111111111"] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": ["ok"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:write", "details": { "requiredScope": "agents:write", "routeId": "skillKnowledgeBases.replace" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:write", "Agent Knowledge"], "summary": "Replace knowledge bases", "description": "Replace knowledge bases.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:write`. Risk class: `standard`. Route ID: `skillKnowledgeBases.replace`.\n\nExample:\n\n```sh\ncurl -sS -X PUT \"https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123/knowledge-bases\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/skills/{skillId}/nodes/{nodeId}/effective-kbs": { "get": { "operationId": "skillKnowledgeBases.listEffectiveForNode", "x-api-key-required-scope": "agents:read", "x-api-key-risk-class": "standard", "x-route-id": "skillKnowledgeBases.listEffectiveForNode", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "skillId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "nodeId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "effective": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string", "enum": ["workspace", "agent", "skill", "node"] } }, "required": ["id", "name", "source"], "additionalProperties": false } }, "chain": { "type": "object", "properties": { "workspace": { "type": "array", "items": { "type": "string" } }, "agent": { "type": "array", "items": { "type": "string" } }, "skill": { "type": "array", "items": { "type": "string" } }, "node": { "type": "array", "items": { "type": "string" } } }, "required": ["workspace", "agent", "skill", "node"], "additionalProperties": false } }, "required": ["effective", "chain"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "skill_123", "name": "effective knowledge bases", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:read", "details": { "requiredScope": "agents:read", "routeId": "skillKnowledgeBases.listEffectiveForNode" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:read", "Skills"], "summary": "Get effective knowledge bases", "description": "Get effective knowledge bases.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:read`. Risk class: `standard`. Route ID: `skillKnowledgeBases.listEffectiveForNode`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123/nodes/node_123/effective-kbs?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/skills/{skillId}/kb-config": { "get": { "operationId": "skillKnowledgeConfig.get", "x-api-key-required-scope": "agents:read", "x-api-key-risk-class": "standard", "x-route-id": "skillKnowledgeConfig.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "skillId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "effective": { "type": "object", "properties": { "topK": { "type": ["number", "null"] }, "filterScore": { "type": ["number", "null"] }, "searchMode": { "type": ["string", "null"] }, "semanticRatio": { "type": ["number", "null"] }, "gqrEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "null" } ] }, "contextWindow": { "type": ["number", "null"] } }, "additionalProperties": false }, "skillOverride": { "type": ["object", "null"], "properties": { "topK": { "type": ["number", "null"] }, "filterScore": { "type": ["number", "null"] }, "searchMode": { "type": ["string", "null"] }, "semanticRatio": { "type": ["number", "null"] }, "gqrEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "null" } ] }, "contextWindow": { "type": ["number", "null"] } }, "additionalProperties": false }, "agentDefault": { "type": "object", "properties": { "topK": { "type": ["number", "null"] }, "filterScore": { "type": ["number", "null"] }, "searchMode": { "type": ["string", "null"] }, "semanticRatio": { "type": ["number", "null"] }, "gqrEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "null" } ] }, "contextWindow": { "type": ["number", "null"] } }, "additionalProperties": false } }, "required": ["effective", "skillOverride", "agentDefault"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "kb_123", "name": "knowledge configuration", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:read", "details": { "requiredScope": "agents:read", "routeId": "skillKnowledgeConfig.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:read", "Agent Knowledge"], "summary": "Get knowledge configuration", "description": "Get knowledge configuration.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:read`. Risk class: `standard`. Route ID: `skillKnowledgeConfig.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123/kb-config?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "patch": { "operationId": "skillKnowledgeConfig.update", "x-api-key-required-scope": "agents:write", "x-api-key-risk-class": "standard", "x-route-id": "skillKnowledgeConfig.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "skillId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "topK": { "type": ["integer", "null"], "exclusiveMinimum": 0 }, "filterScore": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }, "searchMode": { "type": ["string", "null"] }, "semanticRatio": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }, "gqrEnabled": { "type": ["boolean", "null"] }, "contextWindow": { "type": ["integer", "null"], "exclusiveMinimum": 0 } } }, "examples": { "default": { "summary": "Update knowledge configuration request", "value": { "topK": 1, "filterScore": 0, "searchMode": "example", "semanticRatio": 0 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": ["ok"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:write", "details": { "requiredScope": "agents:write", "routeId": "skillKnowledgeConfig.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:write", "Agent Knowledge"], "summary": "Update knowledge configuration", "description": "Update knowledge configuration.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:write`. Risk class: `standard`. Route ID: `skillKnowledgeConfig.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123/kb-config\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{id}/simulations/{sessionId}/dump": { "post": { "operationId": "agents.uploadSimulationDump", "x-api-key-required-scope": "agents:execute", "x-api-key-risk-class": "standard", "x-route-id": "agents.uploadSimulationDump", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "sessionId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tomlContent": { "type": "string", "minLength": 1, "maxLength": 4194304 } }, "required": ["tomlContent"] }, "examples": { "default": { "summary": "Create dump request", "value": { "tomlContent": "[scenario]\nname = \"greeting_smoke_test\"\n" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "blobName": { "type": "string" }, "blobUrl": { "type": "string" }, "uploadedAt": { "type": "string", "format": "date-time" } }, "required": ["blobName", "blobUrl", "uploadedAt"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "agt_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: agents:execute", "details": { "requiredScope": "agents:execute", "routeId": "agents.uploadSimulationDump" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: agents:execute", "Agents"], "summary": "Create dump", "description": "Create dump.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `agents:execute`. Risk class: `standard`. Route ID: `agents.uploadSimulationDump`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/agents/kb_123/simulations/sess_123/dump\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/test-scenarios": { "post": { "operationId": "testScenarios.create", "x-api-key-required-scope": "test-scenarios:write", "x-api-key-risk-class": "standard", "x-route-id": "testScenarios.create", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "mode": { "type": "string", "enum": ["component", "e2e"] }, "tags": { "type": "array", "items": { "type": "string" } }, "definition": { "type": "object", "additionalProperties": {} } }, "required": ["name", "mode", "definition"] }, "examples": { "default": { "summary": "Create test scenarios request", "value": { "name": "Partner support", "mode": "component", "definition": { "key": "value" }, "description": "Used by the partner integration.", "tags": ["example"] } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "mode": { "type": "string", "enum": ["component", "e2e"] }, "tags": { "type": "array", "items": { "type": "string" } }, "definition": { "type": "object", "additionalProperties": true }, "version": { "type": "number" }, "isArchived": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "workspaceId", "name", "description", "mode", "tags", "definition", "version", "isArchived", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "scenario_123", "name": "test scenarios", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: test-scenarios:write", "details": { "requiredScope": "test-scenarios:write", "routeId": "testScenarios.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: test-scenarios:write", "Test Scenarios"], "summary": "Create test scenarios", "description": "Create test scenarios.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `test-scenarios:write`. Risk class: `standard`. Route ID: `testScenarios.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/agents/agt_123/test-scenarios\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "get": { "operationId": "testScenarios.list", "x-api-key-required-scope": "test-scenarios:read", "x-api-key-risk-class": "standard", "x-route-id": "testScenarios.list", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": ["component", "e2e"] }, "required": false, "name": "mode", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "tags", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "mode": { "type": "string", "enum": ["component", "e2e"] }, "tags": { "type": "array", "items": { "type": "string" } }, "definition": { "type": "object", "additionalProperties": true }, "version": { "type": "number" }, "isArchived": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "workspaceId", "name", "description", "mode", "tags", "definition", "version", "isArchived", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "scenario_123", "name": "test scenarios", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: test-scenarios:read", "details": { "requiredScope": "test-scenarios:read", "routeId": "testScenarios.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: test-scenarios:read", "Test Scenarios"], "summary": "Get test scenarios", "description": "Get test scenarios.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `test-scenarios:read`. Risk class: `standard`. Route ID: `testScenarios.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/agt_123/test-scenarios?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/test-scenarios/{id}": { "get": { "operationId": "testScenarios.get", "x-api-key-required-scope": "test-scenarios:read", "x-api-key-risk-class": "standard", "x-route-id": "testScenarios.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "mode": { "type": "string", "enum": ["component", "e2e"] }, "tags": { "type": "array", "items": { "type": "string" } }, "definition": { "type": "object", "additionalProperties": true }, "version": { "type": "number" }, "isArchived": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "workspaceId", "name", "description", "mode", "tags", "definition", "version", "isArchived", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "scenario_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: test-scenarios:read", "details": { "requiredScope": "test-scenarios:read", "routeId": "testScenarios.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: test-scenarios:read", "Test Scenarios"], "summary": "Get test scenarios", "description": "Get test scenarios.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `test-scenarios:read`. Risk class: `standard`. Route ID: `testScenarios.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/agt_123/test-scenarios/kb_123?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "patch": { "operationId": "testScenarios.update", "x-api-key-required-scope": "test-scenarios:write", "x-api-key-risk-class": "standard", "x-route-id": "testScenarios.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "mode": { "type": "string", "enum": ["component", "e2e"] }, "tags": { "type": "array", "items": { "type": "string" } }, "definition": { "type": "object", "additionalProperties": {} } } }, "examples": { "default": { "summary": "Update test scenarios request", "value": { "name": "Partner support", "description": "Used by the partner integration.", "mode": "component", "tags": ["example"] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "agentId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "mode": { "type": "string", "enum": ["component", "e2e"] }, "tags": { "type": "array", "items": { "type": "string" } }, "definition": { "type": "object", "additionalProperties": true }, "version": { "type": "number" }, "isArchived": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentId", "workspaceId", "name", "description", "mode", "tags", "definition", "version", "isArchived", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "scenario_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: test-scenarios:write", "details": { "requiredScope": "test-scenarios:write", "routeId": "testScenarios.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: test-scenarios:write", "Test Scenarios"], "summary": "Update test scenarios", "description": "Update test scenarios.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `test-scenarios:write`. Risk class: `standard`. Route ID: `testScenarios.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/agents/agt_123/test-scenarios/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "testScenarios.delete", "x-api-key-required-scope": "test-scenarios:write", "x-api-key-risk-class": "standard", "x-route-id": "testScenarios.delete", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: test-scenarios:write", "details": { "requiredScope": "test-scenarios:write", "routeId": "testScenarios.delete" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: test-scenarios:write", "Test Scenarios"], "summary": "Delete test scenarios", "description": "Delete test scenarios.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `test-scenarios:write`. Risk class: `standard`. Route ID: `testScenarios.delete`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/agents/agt_123/test-scenarios/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/test-scenarios/import": { "post": { "operationId": "testScenarios.import", "x-api-key-required-scope": "test-scenarios:write", "x-api-key-risk-class": "standard", "x-route-id": "testScenarios.import", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "yaml": { "type": "string", "minLength": 1 } }, "required": ["yaml"] }, "examples": { "default": { "summary": "Import test scenarios request", "value": { "yaml": "name: greeting_smoke_test\nmode: component\n" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "imported": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": ["component", "e2e"] } }, "required": ["id", "name", "mode"], "additionalProperties": false } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "error": { "type": "string" } }, "required": ["name", "error"], "additionalProperties": false } } }, "required": ["imported", "errors"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "scenario_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: test-scenarios:write", "details": { "requiredScope": "test-scenarios:write", "routeId": "testScenarios.import" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: test-scenarios:write", "Test Scenarios"], "summary": "Import test scenarios", "description": "Import test scenarios.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `test-scenarios:write`. Risk class: `standard`. Route ID: `testScenarios.import`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/agents/agt_123/test-scenarios/import\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/test-runs": { "post": { "operationId": "testRuns.create", "x-api-key-required-scope": "test-scenarios:execute", "x-api-key-risk-class": "standard", "x-route-id": "testRuns.create", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scenarioId": { "type": "string", "minLength": 1 }, "configOverride": { "type": "object", "additionalProperties": {} } }, "required": ["scenarioId"] }, "examples": { "default": { "summary": "Create test runs request", "value": { "scenarioId": "scenario_123", "configOverride": { "key": "value" } } } } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "running", "completed", "failed", "cancelled"] }, "scenarioId": { "type": "string" }, "agentVersion": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "_links": { "type": "object", "properties": { "self": { "type": "string" }, "iterations": { "type": "string" } }, "required": ["self", "iterations"], "additionalProperties": false } }, "required": ["id", "status", "scenarioId", "agentVersion", "createdAt", "_links"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "scenario_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: test-scenarios:execute", "details": { "requiredScope": "test-scenarios:execute", "routeId": "testRuns.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: test-scenarios:execute", "Test Scenarios"], "summary": "Create test runs", "description": "Create test runs.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `test-scenarios:execute`. Risk class: `standard`. Route ID: `testRuns.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/agents/agt_123/test-runs\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "get": { "operationId": "testRuns.list", "x-api-key-required-scope": "test-scenarios:read", "x-api-key-risk-class": "standard", "x-route-id": "testRuns.list", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "scenarioId": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "running", "completed", "failed", "cancelled"] }, "agentVersion": { "type": "number" }, "summary": {}, "startedAt": { "type": ["string", "null"], "format": "date-time" }, "completedAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "scenarioId", "status", "agentVersion", "startedAt", "completedAt", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "scenario_123", "name": "test runs", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: test-scenarios:read", "details": { "requiredScope": "test-scenarios:read", "routeId": "testRuns.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: test-scenarios:read", "Test Scenarios"], "summary": "Get test runs", "description": "Get test runs.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `test-scenarios:read`. Risk class: `standard`. Route ID: `testRuns.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/agt_123/test-runs?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/test-runs/{id}": { "get": { "operationId": "testRuns.get", "x-api-key-required-scope": "test-scenarios:read", "x-api-key-risk-class": "standard", "x-route-id": "testRuns.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "scenarioId": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "running", "completed", "failed", "cancelled"] }, "agentVersion": { "type": "number" }, "summary": {}, "startedAt": { "type": ["string", "null"], "format": "date-time" }, "completedAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "progress": { "type": "object", "properties": { "completedIterations": { "type": "number" }, "totalIterations": { "type": "number" } }, "required": ["completedIterations", "totalIterations"], "additionalProperties": false } }, "required": [ "id", "scenarioId", "status", "agentVersion", "startedAt", "completedAt", "createdAt", "progress" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "scenario_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: test-scenarios:read", "details": { "requiredScope": "test-scenarios:read", "routeId": "testRuns.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: test-scenarios:read", "Test Scenarios"], "summary": "Get test runs", "description": "Get test runs.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `test-scenarios:read`. Risk class: `standard`. Route ID: `testRuns.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/agt_123/test-runs/kb_123?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/test-runs/{id}/iterations": { "get": { "operationId": "testRuns.listIterations", "x-api-key-required-scope": "test-scenarios:read", "x-api-key-risk-class": "standard", "x-route-id": "testRuns.listIterations", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "iterationNumber": { "type": "number" }, "passed": { "type": "boolean" }, "overallScore": { "type": ["string", "null"] }, "structuralEvaluation": {}, "qualitativeEvaluation": {}, "conversationLog": {}, "detectedPatterns": {}, "langsmithTraceUrl": { "type": ["string", "null"] }, "durationMs": { "type": ["number", "null"] }, "llmCostUsd": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "runId", "iterationNumber", "passed", "overallScore", "langsmithTraceUrl", "durationMs", "llmCostUsd", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "scenario_123", "name": "iterations", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: test-scenarios:read", "details": { "requiredScope": "test-scenarios:read", "routeId": "testRuns.listIterations" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: test-scenarios:read", "Test Scenarios"], "summary": "Get iterations", "description": "Get iterations.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `test-scenarios:read`. Risk class: `standard`. Route ID: `testRuns.listIterations`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/agents/agt_123/test-runs/kb_123/iterations?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/agents/{agentId}/test-runs/{id}/cancel": { "post": { "operationId": "testRuns.cancel", "x-api-key-required-scope": "test-scenarios:execute", "x-api-key-risk-class": "standard", "x-route-id": "testRuns.cancel", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "agentId", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "scenario_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: test-scenarios:execute", "details": { "requiredScope": "test-scenarios:execute", "routeId": "testRuns.cancel" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: test-scenarios:execute", "Test Scenarios"], "summary": "Cancel test run", "description": "Cancel test run.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `test-scenarios:execute`. Risk class: `standard`. Route ID: `testRuns.cancel`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/agents/agt_123/test-runs/kb_123/cancel\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/calls": { "get": { "operationId": "calls.list", "x-api-key-required-scope": "calls:read", "x-api-key-risk-class": "standard", "x-route-id": "calls.list", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "agentId", "in": "query" }, { "schema": { "type": "string", "enum": ["queued", "registered", "not_connected", "ongoing", "ended", "error"] }, "required": false, "name": "callStatus", "in": "query" }, { "schema": { "type": "string", "enum": ["inbound", "outbound"] }, "required": false, "name": "direction", "in": "query" }, { "schema": { "type": "string", "enum": ["phone", "web"] }, "required": false, "name": "callType", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "agentId": { "type": "string" }, "agentVersion": { "type": ["number", "null"] }, "callStatus": { "type": "string", "enum": [ "queued", "registered", "not_connected", "ongoing", "ended", "error" ] }, "direction": { "type": "string", "enum": ["inbound", "outbound"] }, "callType": { "type": "string", "enum": ["phone", "web"] }, "fromNumber": { "type": ["string", "null"] }, "toNumber": { "type": ["string", "null"] }, "ingressTimestamp": { "type": ["string", "null"], "format": "date-time" }, "sipActiveTimestamp": { "type": ["string", "null"], "format": "date-time" }, "firstAgentPlaybackTimestamp": { "type": ["string", "null"], "format": "date-time" }, "startTimestamp": { "type": ["string", "null"], "format": "date-time" }, "endTimestamp": { "type": ["string", "null"], "format": "date-time" }, "durationMs": { "type": ["number", "null"] }, "transcript": { "type": ["string", "null"] }, "transcriptObject": { "type": ["array", "null"], "items": { "type": "object", "properties": { "role": { "type": "string", "enum": ["agent", "user"] }, "content": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" }, "words": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" } }, "required": ["word", "startMs", "endMs"], "additionalProperties": false } } }, "required": ["role", "content", "startMs", "endMs"], "additionalProperties": false } }, "recordingUrl": { "type": ["string", "null"] }, "recordingMultiChannelUrl": { "type": ["string", "null"] }, "disconnectionReason": { "type": ["string", "null"] }, "metadata": { "type": "object", "additionalProperties": true }, "livekitRoomName": { "type": ["string", "null"] }, "livekitRoomSid": { "type": ["string", "null"] }, "twilioCallSid": { "type": ["string", "null"] }, "analysis": { "type": ["object", "null"], "properties": { "summary": { "type": "string" }, "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral", "unknown"] }, "successful": { "type": "boolean" }, "customData": { "type": "object", "additionalProperties": true } }, "required": ["summary", "sentiment", "successful", "customData"], "additionalProperties": false }, "latency": { "type": ["object", "null"], "properties": { "e2eMs": { "type": "number" }, "sttMs": { "type": "number" }, "llmMs": { "type": "number" }, "ttsMs": { "type": "number" } }, "required": ["e2eMs", "sttMs", "llmMs", "ttsMs"], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "agentId", "agentVersion", "callStatus", "direction", "callType", "fromNumber", "toNumber", "ingressTimestamp", "sipActiveTimestamp", "firstAgentPlaybackTimestamp", "startTimestamp", "endTimestamp", "durationMs", "transcript", "transcriptObject", "recordingUrl", "recordingMultiChannelUrl", "disconnectionReason", "metadata", "livekitRoomName", "livekitRoomSid", "twilioCallSid", "analysis", "latency", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "call_123", "name": "calls", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: calls:read", "details": { "requiredScope": "calls:read", "routeId": "calls.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: calls:read", "Calls"], "summary": "List calls", "description": "List calls.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/calls?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "post": { "operationId": "calls.create", "x-api-key-required-scope": "calls:execute", "x-api-key-risk-class": "high", "x-route-id": "calls.create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "fromNumber": { "type": "string", "minLength": 1 }, "toNumber": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": ["agentId", "fromNumber", "toNumber"] }, "examples": { "default": { "summary": "Create calls request", "value": { "agentId": "agt_123", "fromNumber": "+81312345678", "toNumber": "+819012345678", "metadata": { "externalCustomerId": "cust_123" } } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "agentId": { "type": "string" }, "agentVersion": { "type": ["number", "null"] }, "callStatus": { "type": "string", "enum": ["queued", "registered", "not_connected", "ongoing", "ended", "error"] }, "direction": { "type": "string", "enum": ["inbound", "outbound"] }, "callType": { "type": "string", "enum": ["phone", "web"] }, "fromNumber": { "type": ["string", "null"] }, "toNumber": { "type": ["string", "null"] }, "ingressTimestamp": { "type": ["string", "null"], "format": "date-time" }, "sipActiveTimestamp": { "type": ["string", "null"], "format": "date-time" }, "firstAgentPlaybackTimestamp": { "type": ["string", "null"], "format": "date-time" }, "startTimestamp": { "type": ["string", "null"], "format": "date-time" }, "endTimestamp": { "type": ["string", "null"], "format": "date-time" }, "durationMs": { "type": ["number", "null"] }, "transcript": { "type": ["string", "null"] }, "transcriptObject": { "type": ["array", "null"], "items": { "type": "object", "properties": { "role": { "type": "string", "enum": ["agent", "user"] }, "content": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" }, "words": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" } }, "required": ["word", "startMs", "endMs"], "additionalProperties": false } } }, "required": ["role", "content", "startMs", "endMs"], "additionalProperties": false } }, "recordingUrl": { "type": ["string", "null"] }, "recordingMultiChannelUrl": { "type": ["string", "null"] }, "disconnectionReason": { "type": ["string", "null"] }, "metadata": { "type": "object", "additionalProperties": true }, "livekitRoomName": { "type": ["string", "null"] }, "livekitRoomSid": { "type": ["string", "null"] }, "twilioCallSid": { "type": ["string", "null"] }, "analysis": { "type": ["object", "null"], "properties": { "summary": { "type": "string" }, "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral", "unknown"] }, "successful": { "type": "boolean" }, "customData": { "type": "object", "additionalProperties": true } }, "required": ["summary", "sentiment", "successful", "customData"], "additionalProperties": false }, "latency": { "type": ["object", "null"], "properties": { "e2eMs": { "type": "number" }, "sttMs": { "type": "number" }, "llmMs": { "type": "number" }, "ttsMs": { "type": "number" } }, "required": ["e2eMs", "sttMs", "llmMs", "ttsMs"], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "agentId", "agentVersion", "callStatus", "direction", "callType", "fromNumber", "toNumber", "ingressTimestamp", "sipActiveTimestamp", "firstAgentPlaybackTimestamp", "startTimestamp", "endTimestamp", "durationMs", "transcript", "transcriptObject", "recordingUrl", "recordingMultiChannelUrl", "disconnectionReason", "metadata", "livekitRoomName", "livekitRoomSid", "twilioCallSid", "analysis", "latency", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "call_123", "name": "calls", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: calls:execute", "details": { "requiredScope": "calls:execute", "routeId": "calls.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: calls:execute", "Calls"], "summary": "Create calls", "description": "Create calls.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `calls:execute`. Risk class: `high`. Route ID: `calls.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/calls\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/calls/queue-status": { "get": { "operationId": "calls.queueStatus", "x-api-key-required-scope": "calls:read", "x-api-key-risk-class": "standard", "x-route-id": "calls.queueStatus", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "maxConcurrent": { "type": "number" }, "currentOngoing": { "type": "number" }, "inboundOngoing": { "type": "number" }, "outboundOngoing": { "type": "number" }, "queuedCalls": { "type": "array", "items": { "type": "object", "properties": { "callId": { "type": "string" }, "toNumber": { "type": ["string", "null"] }, "agentId": { "type": "string" }, "queuedAt": { "type": "string", "format": "date-time" }, "position": { "type": "number" }, "estimatedWaitSeconds": { "type": "number" } }, "required": [ "callId", "toNumber", "agentId", "queuedAt", "position", "estimatedWaitSeconds" ], "additionalProperties": false } } }, "required": [ "workspaceId", "maxConcurrent", "currentOngoing", "inboundOngoing", "outboundOngoing", "queuedCalls" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "workspaceId": "ws_123", "maxConcurrent": 10, "currentOngoing": 3, "inboundOngoing": 1, "outboundOngoing": 2, "queuedCalls": [] } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: calls:read", "details": { "requiredScope": "calls:read", "routeId": "calls.queueStatus" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: calls:read", "Calls"], "summary": "List queue status", "description": "List queue status.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.queueStatus`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/calls/queue-status\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/calls/{id}": { "get": { "operationId": "calls.get", "x-api-key-required-scope": "calls:read", "x-api-key-risk-class": "standard", "x-route-id": "calls.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "agentId": { "type": "string" }, "agentVersion": { "type": ["number", "null"] }, "callStatus": { "type": "string", "enum": ["queued", "registered", "not_connected", "ongoing", "ended", "error"] }, "direction": { "type": "string", "enum": ["inbound", "outbound"] }, "callType": { "type": "string", "enum": ["phone", "web"] }, "fromNumber": { "type": ["string", "null"] }, "toNumber": { "type": ["string", "null"] }, "ingressTimestamp": { "type": ["string", "null"], "format": "date-time" }, "sipActiveTimestamp": { "type": ["string", "null"], "format": "date-time" }, "firstAgentPlaybackTimestamp": { "type": ["string", "null"], "format": "date-time" }, "startTimestamp": { "type": ["string", "null"], "format": "date-time" }, "endTimestamp": { "type": ["string", "null"], "format": "date-time" }, "durationMs": { "type": ["number", "null"] }, "transcript": { "type": ["string", "null"] }, "transcriptObject": { "type": ["array", "null"], "items": { "type": "object", "properties": { "role": { "type": "string", "enum": ["agent", "user"] }, "content": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" }, "words": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" } }, "required": ["word", "startMs", "endMs"], "additionalProperties": false } } }, "required": ["role", "content", "startMs", "endMs"], "additionalProperties": false } }, "recordingUrl": { "type": ["string", "null"] }, "recordingMultiChannelUrl": { "type": ["string", "null"] }, "disconnectionReason": { "type": ["string", "null"] }, "metadata": { "type": "object", "additionalProperties": true }, "livekitRoomName": { "type": ["string", "null"] }, "livekitRoomSid": { "type": ["string", "null"] }, "twilioCallSid": { "type": ["string", "null"] }, "analysis": { "type": ["object", "null"], "properties": { "summary": { "type": "string" }, "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral", "unknown"] }, "successful": { "type": "boolean" }, "customData": { "type": "object", "additionalProperties": true } }, "required": ["summary", "sentiment", "successful", "customData"], "additionalProperties": false }, "latency": { "type": ["object", "null"], "properties": { "e2eMs": { "type": "number" }, "sttMs": { "type": "number" }, "llmMs": { "type": "number" }, "ttsMs": { "type": "number" } }, "required": ["e2eMs", "sttMs", "llmMs", "ttsMs"], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "agentId", "agentVersion", "callStatus", "direction", "callType", "fromNumber", "toNumber", "ingressTimestamp", "sipActiveTimestamp", "firstAgentPlaybackTimestamp", "startTimestamp", "endTimestamp", "durationMs", "transcript", "transcriptObject", "recordingUrl", "recordingMultiChannelUrl", "disconnectionReason", "metadata", "livekitRoomName", "livekitRoomSid", "twilioCallSid", "analysis", "latency", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "call_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: calls:read", "details": { "requiredScope": "calls:read", "routeId": "calls.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: calls:read", "Calls"], "summary": "Get calls", "description": "Get calls.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/calls/kb_123?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/calls/phone": { "post": { "operationId": "calls.createPhone", "x-api-key-required-scope": "calls:execute", "x-api-key-risk-class": "high", "x-route-id": "calls.createPhone", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "fromNumber": { "type": "string", "minLength": 1 }, "toNumber": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": ["agentId", "fromNumber", "toNumber"] }, "examples": { "default": { "summary": "Create phone request", "value": { "agentId": "agt_123", "fromNumber": "+81312345678", "toNumber": "+819012345678", "metadata": { "externalCustomerId": "cust_123" } } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "agentId": { "type": "string" }, "agentVersion": { "type": ["number", "null"] }, "callStatus": { "type": "string", "enum": ["queued", "registered", "not_connected", "ongoing", "ended", "error"] }, "direction": { "type": "string", "enum": ["inbound", "outbound"] }, "callType": { "type": "string", "enum": ["phone", "web"] }, "fromNumber": { "type": ["string", "null"] }, "toNumber": { "type": ["string", "null"] }, "ingressTimestamp": { "type": ["string", "null"], "format": "date-time" }, "sipActiveTimestamp": { "type": ["string", "null"], "format": "date-time" }, "firstAgentPlaybackTimestamp": { "type": ["string", "null"], "format": "date-time" }, "startTimestamp": { "type": ["string", "null"], "format": "date-time" }, "endTimestamp": { "type": ["string", "null"], "format": "date-time" }, "durationMs": { "type": ["number", "null"] }, "transcript": { "type": ["string", "null"] }, "transcriptObject": { "type": ["array", "null"], "items": { "type": "object", "properties": { "role": { "type": "string", "enum": ["agent", "user"] }, "content": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" }, "words": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" } }, "required": ["word", "startMs", "endMs"], "additionalProperties": false } } }, "required": ["role", "content", "startMs", "endMs"], "additionalProperties": false } }, "recordingUrl": { "type": ["string", "null"] }, "recordingMultiChannelUrl": { "type": ["string", "null"] }, "disconnectionReason": { "type": ["string", "null"] }, "metadata": { "type": "object", "additionalProperties": true }, "livekitRoomName": { "type": ["string", "null"] }, "livekitRoomSid": { "type": ["string", "null"] }, "twilioCallSid": { "type": ["string", "null"] }, "analysis": { "type": ["object", "null"], "properties": { "summary": { "type": "string" }, "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral", "unknown"] }, "successful": { "type": "boolean" }, "customData": { "type": "object", "additionalProperties": true } }, "required": ["summary", "sentiment", "successful", "customData"], "additionalProperties": false }, "latency": { "type": ["object", "null"], "properties": { "e2eMs": { "type": "number" }, "sttMs": { "type": "number" }, "llmMs": { "type": "number" }, "ttsMs": { "type": "number" } }, "required": ["e2eMs", "sttMs", "llmMs", "ttsMs"], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "accessToken": { "type": "string" }, "livekitUrl": { "type": "string" }, "simulated": { "type": "boolean" } }, "required": [ "id", "workspaceId", "agentId", "agentVersion", "callStatus", "direction", "callType", "fromNumber", "toNumber", "ingressTimestamp", "sipActiveTimestamp", "firstAgentPlaybackTimestamp", "startTimestamp", "endTimestamp", "durationMs", "transcript", "transcriptObject", "recordingUrl", "recordingMultiChannelUrl", "disconnectionReason", "metadata", "livekitRoomName", "livekitRoomSid", "twilioCallSid", "analysis", "latency", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "call_123", "name": "phone", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: calls:execute", "details": { "requiredScope": "calls:execute", "routeId": "calls.createPhone" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: calls:execute", "Calls"], "summary": "Create phone", "description": "Create phone.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `calls:execute`. Risk class: `high`. Route ID: `calls.createPhone`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/calls/phone\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/calls/web": { "post": { "operationId": "calls.createWeb", "x-api-key-required-scope": "calls:execute", "x-api-key-risk-class": "high", "x-route-id": "calls.createWeb", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": ["agentId"] }, "examples": { "default": { "summary": "Create web request", "value": { "agentId": "agt_123", "metadata": { "source": "partner_console" } } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "agentId": { "type": "string" }, "agentVersion": { "type": ["number", "null"] }, "callStatus": { "type": "string", "enum": ["queued", "registered", "not_connected", "ongoing", "ended", "error"] }, "direction": { "type": "string", "enum": ["inbound", "outbound"] }, "callType": { "type": "string", "enum": ["phone", "web"] }, "fromNumber": { "type": ["string", "null"] }, "toNumber": { "type": ["string", "null"] }, "ingressTimestamp": { "type": ["string", "null"], "format": "date-time" }, "sipActiveTimestamp": { "type": ["string", "null"], "format": "date-time" }, "firstAgentPlaybackTimestamp": { "type": ["string", "null"], "format": "date-time" }, "startTimestamp": { "type": ["string", "null"], "format": "date-time" }, "endTimestamp": { "type": ["string", "null"], "format": "date-time" }, "durationMs": { "type": ["number", "null"] }, "transcript": { "type": ["string", "null"] }, "transcriptObject": { "type": ["array", "null"], "items": { "type": "object", "properties": { "role": { "type": "string", "enum": ["agent", "user"] }, "content": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" }, "words": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" } }, "required": ["word", "startMs", "endMs"], "additionalProperties": false } } }, "required": ["role", "content", "startMs", "endMs"], "additionalProperties": false } }, "recordingUrl": { "type": ["string", "null"] }, "recordingMultiChannelUrl": { "type": ["string", "null"] }, "disconnectionReason": { "type": ["string", "null"] }, "metadata": { "type": "object", "additionalProperties": true }, "livekitRoomName": { "type": ["string", "null"] }, "livekitRoomSid": { "type": ["string", "null"] }, "twilioCallSid": { "type": ["string", "null"] }, "analysis": { "type": ["object", "null"], "properties": { "summary": { "type": "string" }, "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral", "unknown"] }, "successful": { "type": "boolean" }, "customData": { "type": "object", "additionalProperties": true } }, "required": ["summary", "sentiment", "successful", "customData"], "additionalProperties": false }, "latency": { "type": ["object", "null"], "properties": { "e2eMs": { "type": "number" }, "sttMs": { "type": "number" }, "llmMs": { "type": "number" }, "ttsMs": { "type": "number" } }, "required": ["e2eMs", "sttMs", "llmMs", "ttsMs"], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "accessToken": { "type": "string" }, "livekitUrl": { "type": "string" }, "simulated": { "type": "boolean" } }, "required": [ "id", "workspaceId", "agentId", "agentVersion", "callStatus", "direction", "callType", "fromNumber", "toNumber", "ingressTimestamp", "sipActiveTimestamp", "firstAgentPlaybackTimestamp", "startTimestamp", "endTimestamp", "durationMs", "transcript", "transcriptObject", "recordingUrl", "recordingMultiChannelUrl", "disconnectionReason", "metadata", "livekitRoomName", "livekitRoomSid", "twilioCallSid", "analysis", "latency", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "call_123", "name": "web", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: calls:execute", "details": { "requiredScope": "calls:execute", "routeId": "calls.createWeb" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: calls:execute", "Calls"], "summary": "Create web", "description": "Create web.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `calls:execute`. Risk class: `high`. Route ID: `calls.createWeb`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/calls/web\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/calls/{id}/recording": { "get": { "operationId": "calls.getRecording", "x-api-key-required-scope": "calls:read", "x-api-key-risk-class": "standard", "x-route-id": "calls.getRecording", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "recordingUrl": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["id", "recordingUrl", "expiresAt"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "call_123", "name": "recording", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: calls:read", "details": { "requiredScope": "calls:read", "routeId": "calls.getRecording" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: calls:read", "Calls"], "summary": "Get recording", "description": "Get recording.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.getRecording`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/calls/kb_123/recording?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/calls/{id}/transcript": { "get": { "operationId": "calls.getTranscript", "x-api-key-required-scope": "calls:read", "x-api-key-risk-class": "standard", "x-route-id": "calls.getTranscript", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "transcript": { "type": ["string", "null"] }, "transcriptObject": { "type": ["array", "null"], "items": { "type": "object", "properties": { "role": { "type": "string", "enum": ["agent", "user"] }, "content": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" }, "words": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "startMs": { "type": "number" }, "endMs": { "type": "number" } }, "required": ["word", "startMs", "endMs"], "additionalProperties": false } } }, "required": ["role", "content", "startMs", "endMs"], "additionalProperties": false } } }, "required": ["id", "transcript", "transcriptObject"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "call_123", "name": "transcript", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: calls:read", "details": { "requiredScope": "calls:read", "routeId": "calls.getTranscript" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: calls:read", "Calls"], "summary": "Get transcript", "description": "Get transcript.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.getTranscript`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/calls/kb_123/transcript?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/calls/{id}/turn-metrics": { "get": { "operationId": "calls.getTurnMetrics", "x-api-key-required-scope": "calls:read", "x-api-key-risk-class": "standard", "x-route-id": "calls.getTurnMetrics", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "turnIndex": { "type": "number" }, "speechId": { "type": "string" }, "vadToEouMs": { "type": ["number", "null"] }, "sttFinalMs": { "type": ["number", "null"] }, "llmTtftMs": { "type": ["number", "null"] }, "ttsTtfbMs": { "type": ["number", "null"] }, "e2eMeasuredMs": { "type": ["number", "null"] }, "e2eAdditiveMs": { "type": ["number", "null"] } }, "required": [ "turnIndex", "speechId", "vadToEouMs", "sttFinalMs", "llmTtftMs", "ttsTtfbMs", "e2eMeasuredMs", "e2eAdditiveMs" ], "additionalProperties": false } }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "call_123", "name": "turn metrics", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: calls:read", "details": { "requiredScope": "calls:read", "routeId": "calls.getTurnMetrics" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: calls:read", "Calls"], "summary": "Get turn metrics", "description": "Get turn metrics.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.getTurnMetrics`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/calls/kb_123/turn-metrics?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/phone-numbers": { "get": { "operationId": "phoneNumbers.list", "x-api-key-required-scope": "phone-numbers:read", "x-api-key-risk-class": "standard", "x-route-id": "phoneNumbers.list", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": ["string", "null"] }, "phoneNumber": { "type": "string" }, "phoneNumberPretty": { "type": ["string", "null"] }, "provider": { "type": "string" }, "providerNumberSid": { "type": ["string", "null"] }, "inboundAgentId": { "type": ["string", "null"] }, "outboundAgentId": { "type": ["string", "null"] }, "nickname": { "type": ["string", "null"] }, "areaCode": { "type": ["number", "null"] }, "sipTrunkId": { "type": ["string", "null"] }, "sipConfig": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "phoneNumber", "phoneNumberPretty", "provider", "providerNumberSid", "inboundAgentId", "outboundAgentId", "nickname", "areaCode", "sipTrunkId", "sipConfig", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "pn_123", "name": "phone numbers", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: phone-numbers:read", "details": { "requiredScope": "phone-numbers:read", "routeId": "phoneNumbers.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: phone-numbers:read", "Phone Numbers"], "summary": "List phone numbers", "description": "List phone numbers.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `phone-numbers:read`. Risk class: `standard`. Route ID: `phoneNumbers.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/phone-numbers?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "post": { "operationId": "phoneNumbers.buy", "x-api-key-required-scope": "phone-numbers:write", "x-api-key-risk-class": "high", "x-route-id": "phoneNumbers.buy", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "areaCode": { "type": "number" }, "nickname": { "type": "string" }, "inboundAgentId": { "type": "string" }, "outboundAgentId": { "type": "string" } } }, "examples": { "default": { "summary": "Create phone numbers request", "value": { "areaCode": 1, "nickname": "Partner support", "inboundAgentId": "inboundAgent_123", "outboundAgentId": "outboundAgent_123" } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": ["string", "null"] }, "phoneNumber": { "type": "string" }, "phoneNumberPretty": { "type": ["string", "null"] }, "provider": { "type": "string" }, "providerNumberSid": { "type": ["string", "null"] }, "inboundAgentId": { "type": ["string", "null"] }, "outboundAgentId": { "type": ["string", "null"] }, "nickname": { "type": ["string", "null"] }, "areaCode": { "type": ["number", "null"] }, "sipTrunkId": { "type": ["string", "null"] }, "sipConfig": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "phoneNumber", "phoneNumberPretty", "provider", "providerNumberSid", "inboundAgentId", "outboundAgentId", "nickname", "areaCode", "sipTrunkId", "sipConfig", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "pn_123", "name": "phone numbers", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: phone-numbers:write", "details": { "requiredScope": "phone-numbers:write", "routeId": "phoneNumbers.buy" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: phone-numbers:write", "Phone Numbers"], "summary": "Create phone numbers", "description": "Create phone numbers.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `phone-numbers:write`. Risk class: `high`. Route ID: `phoneNumbers.buy`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/phone-numbers\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/phone-numbers/import": { "post": { "operationId": "phoneNumbers.import", "x-api-key-required-scope": "phone-numbers:write", "x-api-key-risk-class": "high", "x-route-id": "phoneNumbers.import", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "phoneNumber": { "type": "string", "minLength": 1 }, "nickname": { "type": "string" }, "inboundAgentId": { "type": "string" }, "outboundAgentId": { "type": "string" } }, "required": ["phoneNumber"] }, "examples": { "default": { "summary": "Import phone numbers request", "value": { "phoneNumber": "+81312345678", "nickname": "Partner support", "inboundAgentId": "inboundAgent_123", "outboundAgentId": "outboundAgent_123" } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": ["string", "null"] }, "phoneNumber": { "type": "string" }, "phoneNumberPretty": { "type": ["string", "null"] }, "provider": { "type": "string" }, "providerNumberSid": { "type": ["string", "null"] }, "inboundAgentId": { "type": ["string", "null"] }, "outboundAgentId": { "type": ["string", "null"] }, "nickname": { "type": ["string", "null"] }, "areaCode": { "type": ["number", "null"] }, "sipTrunkId": { "type": ["string", "null"] }, "sipConfig": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "phoneNumber", "phoneNumberPretty", "provider", "providerNumberSid", "inboundAgentId", "outboundAgentId", "nickname", "areaCode", "sipTrunkId", "sipConfig", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "pn_123", "name": "import phone numbers", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: phone-numbers:write", "details": { "requiredScope": "phone-numbers:write", "routeId": "phoneNumbers.import" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: phone-numbers:write", "Phone Numbers"], "summary": "Import phone numbers", "description": "Import phone numbers.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `phone-numbers:write`. Risk class: `high`. Route ID: `phoneNumbers.import`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/phone-numbers/import\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/phone-numbers/{id}": { "get": { "operationId": "phoneNumbers.get", "x-api-key-required-scope": "phone-numbers:read", "x-api-key-risk-class": "standard", "x-route-id": "phoneNumbers.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": ["string", "null"] }, "phoneNumber": { "type": "string" }, "phoneNumberPretty": { "type": ["string", "null"] }, "provider": { "type": "string" }, "providerNumberSid": { "type": ["string", "null"] }, "inboundAgentId": { "type": ["string", "null"] }, "outboundAgentId": { "type": ["string", "null"] }, "nickname": { "type": ["string", "null"] }, "areaCode": { "type": ["number", "null"] }, "sipTrunkId": { "type": ["string", "null"] }, "sipConfig": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "phoneNumber", "phoneNumberPretty", "provider", "providerNumberSid", "inboundAgentId", "outboundAgentId", "nickname", "areaCode", "sipTrunkId", "sipConfig", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "pn_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: phone-numbers:read", "details": { "requiredScope": "phone-numbers:read", "routeId": "phoneNumbers.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: phone-numbers:read", "Phone Numbers"], "summary": "Get phone numbers", "description": "Get phone numbers.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `phone-numbers:read`. Risk class: `standard`. Route ID: `phoneNumbers.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/phone-numbers/kb_123?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "patch": { "operationId": "phoneNumbers.update", "x-api-key-required-scope": "phone-numbers:write", "x-api-key-risk-class": "high", "x-route-id": "phoneNumbers.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "nickname": { "type": "string" }, "inboundAgentId": { "type": ["string", "null"] }, "outboundAgentId": { "type": ["string", "null"] } } }, "examples": { "default": { "summary": "Update phone numbers request", "value": { "nickname": "Partner support", "inboundAgentId": "inboundAgent_123", "outboundAgentId": "outboundAgent_123" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": ["string", "null"] }, "phoneNumber": { "type": "string" }, "phoneNumberPretty": { "type": ["string", "null"] }, "provider": { "type": "string" }, "providerNumberSid": { "type": ["string", "null"] }, "inboundAgentId": { "type": ["string", "null"] }, "outboundAgentId": { "type": ["string", "null"] }, "nickname": { "type": ["string", "null"] }, "areaCode": { "type": ["number", "null"] }, "sipTrunkId": { "type": ["string", "null"] }, "sipConfig": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "phoneNumber", "phoneNumberPretty", "provider", "providerNumberSid", "inboundAgentId", "outboundAgentId", "nickname", "areaCode", "sipTrunkId", "sipConfig", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "pn_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: phone-numbers:write", "details": { "requiredScope": "phone-numbers:write", "routeId": "phoneNumbers.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: phone-numbers:write", "Phone Numbers"], "summary": "Update phone numbers", "description": "Update phone numbers.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `phone-numbers:write`. Risk class: `high`. Route ID: `phoneNumbers.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/phone-numbers/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "phoneNumbers.release", "x-api-key-required-scope": "phone-numbers:write", "x-api-key-risk-class": "high", "x-route-id": "phoneNumbers.release", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: phone-numbers:write", "details": { "requiredScope": "phone-numbers:write", "routeId": "phoneNumbers.release" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: phone-numbers:write", "Phone Numbers"], "summary": "Delete phone numbers", "description": "Delete phone numbers.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `phone-numbers:write`. Risk class: `high`. Route ID: `phoneNumbers.release`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/phone-numbers/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/api-keys": { "get": { "operationId": "apiKeys.list", "x-api-key-required-scope": "api-keys:read", "x-api-key-risk-class": "standard", "x-route-id": "apiKeys.list", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "keyPrefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "lastUsedAt": { "type": ["string", "null"], "format": "date-time" }, "expiresAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "keyPrefix", "scopes", "lastUsedAt", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "key_123", "name": "API keys", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: api-keys:read", "details": { "requiredScope": "api-keys:read", "routeId": "apiKeys.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: api-keys:read", "API Keys"], "summary": "List API keys", "description": "List API keys.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `api-keys:read`. Risk class: `standard`. Route ID: `apiKeys.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/api-keys?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "post": { "operationId": "apiKeys.create", "x-api-key-required-scope": "api-keys:write", "x-api-key-risk-class": "high", "x-route-id": "apiKeys.create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": ["name", "scopes"] }, "examples": { "default": { "summary": "Create API keys request", "value": { "name": "Partner support", "scopes": ["example"], "expiresAt": "2026-06-01T00:00:00Z" } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "keyPrefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "lastUsedAt": { "type": ["string", "null"], "format": "date-time" }, "expiresAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "key": { "type": "string" } }, "required": [ "id", "workspaceId", "name", "keyPrefix", "scopes", "lastUsedAt", "expiresAt", "createdAt", "updatedAt", "key" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "key_123", "name": "API keys", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: api-keys:write", "details": { "requiredScope": "api-keys:write", "routeId": "apiKeys.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: api-keys:write", "API Keys"], "summary": "Create API keys", "description": "Create API keys.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `api-keys:write`. Risk class: `high`. Route ID: `apiKeys.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/api-keys\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/api-keys/{id}/rotate": { "post": { "operationId": "apiKeys.rotate", "x-api-key-required-scope": "api-keys:write", "x-api-key-risk-class": "high", "x-route-id": "apiKeys.rotate", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "keyPrefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "lastUsedAt": { "type": ["string", "null"], "format": "date-time" }, "expiresAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "key": { "type": "string" } }, "required": [ "id", "workspaceId", "name", "keyPrefix", "scopes", "lastUsedAt", "expiresAt", "createdAt", "updatedAt", "key" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "key_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: api-keys:write", "details": { "requiredScope": "api-keys:write", "routeId": "apiKeys.rotate" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: api-keys:write", "API Keys"], "summary": "Create rotate", "description": "Create rotate.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `api-keys:write`. Risk class: `high`. Route ID: `apiKeys.rotate`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/api-keys/kb_123/rotate\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/api-keys/{id}": { "delete": { "operationId": "apiKeys.revoke", "x-api-key-required-scope": "api-keys:admin", "x-api-key-risk-class": "high", "x-route-id": "apiKeys.revoke", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: api-keys:admin", "details": { "requiredScope": "api-keys:admin", "routeId": "apiKeys.revoke" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: api-keys:admin", "API Keys"], "summary": "Delete API keys", "description": "Delete API keys.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `api-keys:admin`. Risk class: `high`. Route ID: `apiKeys.revoke`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/api-keys/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/webhooks": { "get": { "operationId": "webhooks.list", "x-api-key-required-scope": "webhooks:read", "x-api-key-risk-class": "standard", "x-route-id": "webhooks.list", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "call.started", "call.ended", "call.analyzed", "agent.updated", "phone_number.created", "phone_number.deleted" ] } }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "url", "events", "customHeaders", "isActive", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "wh_123", "name": "webhooks", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: webhooks:read", "details": { "requiredScope": "webhooks:read", "routeId": "webhooks.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: webhooks:read", "Webhooks"], "summary": "List webhooks", "description": "List webhooks.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `webhooks:read`. Risk class: `standard`. Route ID: `webhooks.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/webhooks?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "post": { "operationId": "webhooks.create", "x-api-key-required-scope": "webhooks:write", "x-api-key-risk-class": "high", "x-route-id": "webhooks.create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "call.started", "call.ended", "call.analyzed", "agent.updated", "phone_number.created", "phone_number.deleted" ] }, "minItems": 1 }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": ["url", "events"] }, "examples": { "default": { "summary": "Create webhooks request", "value": { "url": "https://partner.example/webhooks/voiceagent", "events": ["call.started", "call.ended"], "customHeaders": { "X-Partner-Tenant": "tokyo" } } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "call.started", "call.ended", "call.analyzed", "agent.updated", "phone_number.created", "phone_number.deleted" ] } }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string" } }, "required": [ "id", "workspaceId", "url", "events", "customHeaders", "isActive", "createdAt", "updatedAt", "secret" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "wh_123", "name": "webhooks", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: webhooks:write", "details": { "requiredScope": "webhooks:write", "routeId": "webhooks.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: webhooks:write", "Webhooks"], "summary": "Create webhooks", "description": "Create webhooks.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `webhooks:write`. Risk class: `high`. Route ID: `webhooks.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/webhooks\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/webhooks/{id}": { "patch": { "operationId": "webhooks.update", "x-api-key-required-scope": "webhooks:write", "x-api-key-risk-class": "high", "x-route-id": "webhooks.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "call.started", "call.ended", "call.analyzed", "agent.updated", "phone_number.created", "phone_number.deleted" ] }, "minItems": 1 }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } }, "isActive": { "type": "boolean" } } }, "examples": { "default": { "summary": "Update webhooks request", "value": { "url": "https://partner.example/webhooks/voiceagent", "events": ["call.started", "call.ended"], "customHeaders": { "X-Partner-Tenant": "tokyo" } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "call.started", "call.ended", "call.analyzed", "agent.updated", "phone_number.created", "phone_number.deleted" ] } }, "customHeaders": { "type": "object", "additionalProperties": { "type": "string" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "url", "events", "customHeaders", "isActive", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "wh_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: webhooks:write", "details": { "requiredScope": "webhooks:write", "routeId": "webhooks.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: webhooks:write", "Webhooks"], "summary": "Update webhooks", "description": "Update webhooks.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `webhooks:write`. Risk class: `high`. Route ID: `webhooks.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/webhooks/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "webhooks.delete", "x-api-key-required-scope": "webhooks:write", "x-api-key-risk-class": "high", "x-route-id": "webhooks.delete", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: webhooks:write", "details": { "requiredScope": "webhooks:write", "routeId": "webhooks.delete" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: webhooks:write", "Webhooks"], "summary": "Delete webhooks", "description": "Delete webhooks.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `webhooks:write`. Risk class: `high`. Route ID: `webhooks.delete`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/webhooks/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/webhooks/{id}/test": { "post": { "operationId": "webhooks.test", "x-api-key-required-scope": "webhooks:execute", "x-api-key-risk-class": "standard", "x-route-id": "webhooks.test", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": ["number", "null"] }, "durationMs": { "type": "number" }, "responseBody": { "type": ["string", "null"] } }, "required": ["statusCode", "durationMs", "responseBody"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "wh_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: webhooks:execute", "details": { "requiredScope": "webhooks:execute", "routeId": "webhooks.test" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: webhooks:execute", "Webhooks"], "summary": "Test webhooks", "description": "Test webhooks.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `webhooks:execute`. Risk class: `standard`. Route ID: `webhooks.test`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/webhooks/kb_123/test\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/workspace": { "get": { "operationId": "workspace.get", "x-api-key-required-scope": "workspace:read", "x-api-key-risk-class": "standard", "x-route-id": "workspace.get", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string", "enum": ["free", "pro", "enterprise"] }, "defaultLanguage": { "type": "string" }, "autoRecordCalls": { "type": "boolean" }, "isActive": { "type": "boolean" }, "settings": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "companyName": { "type": "string" } }, "additionalProperties": false }, "features": { "type": "object", "properties": { "webCallEnabled": { "type": "boolean" }, "maxAgents": { "type": "number" } }, "additionalProperties": false }, "auth": { "type": "object", "properties": { "allowedDomains": { "type": "array", "items": { "type": "string" } }, "entraIdTenantId": { "type": "string" } }, "additionalProperties": false }, "callLimits": { "type": "object", "properties": { "maxConcurrent": { "type": "number" }, "busyBehavior": { "type": "string" }, "busyGuidanceFileName": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "releaseChannel": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "plan", "defaultLanguage", "autoRecordCalls", "isActive", "settings", "releaseChannel", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "ws_123", "name": "workspace", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: workspace:read", "details": { "requiredScope": "workspace:read", "routeId": "workspace.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: workspace:read", "Workspace"], "summary": "List workspace", "description": "List workspace.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `workspace:read`. Risk class: `standard`. Route ID: `workspace.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/workspace?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "patch": { "operationId": "workspace.update", "x-api-key-required-scope": "workspace:write", "x-api-key-risk-class": "standard", "x-route-id": "workspace.update", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "slug": { "type": "string", "minLength": 1, "maxLength": 255 }, "defaultLanguage": { "type": "string", "minLength": 1, "maxLength": 10 }, "autoRecordCalls": { "type": "boolean" } } }, "examples": { "default": { "summary": "Update workspace request", "value": { "name": "Partner support", "slug": "customer-records", "defaultLanguage": "ja", "autoRecordCalls": true } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string", "enum": ["free", "pro", "enterprise"] }, "defaultLanguage": { "type": "string" }, "autoRecordCalls": { "type": "boolean" }, "isActive": { "type": "boolean" }, "settings": { "type": "object", "properties": { "branding": { "type": "object", "properties": { "logoUrl": { "type": "string" }, "primaryColor": { "type": "string" }, "companyName": { "type": "string" } }, "additionalProperties": false }, "features": { "type": "object", "properties": { "webCallEnabled": { "type": "boolean" }, "maxAgents": { "type": "number" } }, "additionalProperties": false }, "auth": { "type": "object", "properties": { "allowedDomains": { "type": "array", "items": { "type": "string" } }, "entraIdTenantId": { "type": "string" } }, "additionalProperties": false }, "callLimits": { "type": "object", "properties": { "maxConcurrent": { "type": "number" }, "busyBehavior": { "type": "string" }, "busyGuidanceFileName": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }, "releaseChannel": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "plan", "defaultLanguage", "autoRecordCalls", "isActive", "settings", "releaseChannel", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "ws_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: workspace:write", "details": { "requiredScope": "workspace:write", "routeId": "workspace.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: workspace:write", "Workspace"], "summary": "Update workspace", "description": "Update workspace.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `workspace:write`. Risk class: `standard`. Route ID: `workspace.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/workspace\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "workspace.delete", "x-api-key-required-scope": "workspace:admin", "x-api-key-risk-class": "high", "x-route-id": "workspace.delete", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: workspace:admin", "details": { "requiredScope": "workspace:admin", "routeId": "workspace.delete" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: workspace:admin", "Workspace"], "summary": "Delete workspace", "description": "Delete workspace.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `workspace:admin`. Risk class: `high`. Route ID: `workspace.delete`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/workspace\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/workspace/me/role": { "get": { "operationId": "workspace.getMyRole", "x-api-key-required-scope": "workspace:read", "x-api-key-risk-class": "standard", "x-route-id": "workspace.getMyRole", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": ["owner", "admin", "member"] } }, "required": ["role"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "ws_123", "name": "role", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: workspace:read", "details": { "requiredScope": "workspace:read", "routeId": "workspace.getMyRole" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: workspace:read", "Workspace"], "summary": "List role", "description": "List role.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `workspace:read`. Risk class: `standard`. Route ID: `workspace.getMyRole`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/workspace/me/role?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/workspace/members": { "get": { "operationId": "workspaceMembers.list", "x-api-key-required-scope": "workspace:read", "x-api-key-risk-class": "standard", "x-route-id": "workspaceMembers.list", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string", "enum": ["owner", "admin", "member"] }, "userEmail": { "type": ["string", "null"] }, "userName": { "type": ["string", "null"] }, "userImage": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "userId", "role", "userEmail", "userName", "userImage", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "ws_123", "name": "members", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: workspace:read", "details": { "requiredScope": "workspace:read", "routeId": "workspaceMembers.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: workspace:read", "Workspace"], "summary": "List members", "description": "List members.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `workspace:read`. Risk class: `standard`. Route ID: `workspaceMembers.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/workspace/members?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/workspace/members/{memberId}": { "patch": { "operationId": "workspaceMembers.update", "x-api-key-required-scope": "workspace:admin", "x-api-key-risk-class": "high", "x-route-id": "workspaceMembers.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "memberId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": ["admin", "member"] } }, "required": ["role"] }, "examples": { "default": { "summary": "Update members request", "value": { "role": "admin" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "userId": { "type": "string" }, "role": { "type": "string", "enum": ["owner", "admin", "member"] }, "userEmail": { "type": ["string", "null"] }, "userName": { "type": ["string", "null"] }, "userImage": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "userId", "role", "userEmail", "userName", "userImage", "createdAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "ws_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: workspace:admin", "details": { "requiredScope": "workspace:admin", "routeId": "workspaceMembers.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: workspace:admin", "Workspace"], "summary": "Update members", "description": "Update members.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `workspace:admin`. Risk class: `high`. Route ID: `workspaceMembers.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/workspace/members/mem_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "workspaceMembers.remove", "x-api-key-required-scope": "workspace:admin", "x-api-key-risk-class": "high", "x-route-id": "workspaceMembers.remove", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "memberId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: workspace:admin", "details": { "requiredScope": "workspace:admin", "routeId": "workspaceMembers.remove" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: workspace:admin", "Workspace"], "summary": "Delete members", "description": "Delete members.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `workspace:admin`. Risk class: `high`. Route ID: `workspaceMembers.remove`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/workspace/members/mem_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/analytics": { "get": { "operationId": "analytics.get", "x-api-key-required-scope": "analytics:read", "x-api-key-risk-class": "standard", "x-route-id": "analytics.get", "parameters": [ { "schema": { "type": "string", "enum": ["7d", "30d", "90d"], "default": "30d" }, "required": false, "name": "period", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalCalls": { "type": "number" }, "avgDurationMs": { "type": "number" }, "successRate": { "type": "number" }, "avgE2eLatencyMs": { "type": "number" }, "callsByDate": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "count": { "type": "number" } }, "required": ["date", "count"], "additionalProperties": false } }, "callsByHour": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "number" }, "count": { "type": "number" } }, "required": ["hour", "count"], "additionalProperties": false } }, "callOutcomes": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued", "registered", "not_connected", "ongoing", "ended", "error" ] }, "count": { "type": "number" } }, "required": ["status", "count"], "additionalProperties": false } } }, "required": [ "totalCalls", "avgDurationMs", "successRate", "avgE2eLatencyMs", "callsByDate", "callsByHour", "callOutcomes" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "analytics_123", "name": "analytics", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: analytics:read", "details": { "requiredScope": "analytics:read", "routeId": "analytics.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: analytics:read", "Analytics"], "summary": "List analytics", "description": "List analytics.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `analytics:read`. Risk class: `standard`. Route ID: `analytics.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/analytics?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/knowledge-bases/workspace-defaults": { "get": { "operationId": "workspaceDefaults.listKnowledgeBases", "x-api-key-required-scope": "workspace:read", "x-api-key-risk-class": "standard", "x-route-id": "workspaceDefaults.listKnowledgeBases", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "documentCount": { "type": "number" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "chunkConfig": { "type": "object", "properties": { "maxChunkChars": { "type": "number" }, "minChunkChars": { "type": "number" }, "overlapSentences": { "type": "number" }, "splitThreshold": { "type": "number" } }, "additionalProperties": false }, "contentVersion": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "description", "documentCount", "status", "chunkConfig", "contentVersion", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "kb_123", "name": "workspace defaults", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: workspace:read", "details": { "requiredScope": "workspace:read", "routeId": "workspaceDefaults.listKnowledgeBases" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: workspace:read", "Knowledge Bases"], "summary": "List workspace defaults", "description": "List workspace defaults.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `workspace:read`. Risk class: `standard`. Route ID: `workspaceDefaults.listKnowledgeBases`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/knowledge-bases/workspace-defaults?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "put": { "operationId": "workspaceDefaults.replaceKnowledgeBases", "x-api-key-required-scope": "workspace:admin", "x-api-key-risk-class": "high", "x-route-id": "workspaceDefaults.replaceKnowledgeBases", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "knowledgeBaseIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": ["knowledgeBaseIds"] }, "examples": { "default": { "summary": "Replace workspace defaults request", "value": { "knowledgeBaseIds": ["11111111-1111-4111-8111-111111111111"] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": ["ok"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: workspace:admin", "details": { "requiredScope": "workspace:admin", "routeId": "workspaceDefaults.replaceKnowledgeBases" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: workspace:admin", "Knowledge Bases"], "summary": "Replace workspace defaults", "description": "Replace workspace defaults.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `workspace:admin`. Risk class: `high`. Route ID: `workspaceDefaults.replaceKnowledgeBases`.\n\nExample:\n\n```sh\ncurl -sS -X PUT \"https://api.voiceagent.example/api/v1/knowledge-bases/workspace-defaults\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/knowledge-bases/{kbId}/usage": { "get": { "operationId": "knowledgeBaseUsage.get", "x-api-key-required-scope": "knowledge-bases:read", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBaseUsage.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "kbId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "knowledgeBaseId": { "type": "string" }, "isWorkspaceDefault": { "type": "boolean" }, "agents": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "agentName": { "type": "string" }, "viaWorkspaceDefault": { "type": "boolean" }, "viaAgentBinding": { "type": "boolean" }, "skills": { "type": "array", "items": { "type": "object", "properties": { "skillId": { "type": "string" }, "skillName": { "type": "string" }, "viaOverride": { "type": "boolean" } }, "required": ["skillId", "skillName", "viaOverride"], "additionalProperties": false } } }, "required": [ "agentId", "agentName", "viaWorkspaceDefault", "viaAgentBinding", "skills" ], "additionalProperties": false } }, "totals": { "type": "object", "properties": { "agents": { "type": "number" }, "skills": { "type": "number" } }, "required": ["agents", "skills"], "additionalProperties": false } }, "required": ["knowledgeBaseId", "isWorkspaceDefault", "agents", "totals"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "kb_123", "name": "usage", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:read", "details": { "requiredScope": "knowledge-bases:read", "routeId": "knowledgeBaseUsage.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:read", "Knowledge Bases"], "summary": "List usage", "description": "List usage.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBaseUsage.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/knowledge-bases/{kbId}/usage?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/knowledge-bases": { "get": { "operationId": "knowledgeBases.list", "x-api-key-required-scope": "knowledge-bases:read", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBases.list", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "documentCount": { "type": "number" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "chunkConfig": { "type": "object", "properties": { "maxChunkChars": { "type": "number" }, "minChunkChars": { "type": "number" }, "overlapSentences": { "type": "number" }, "splitThreshold": { "type": "number" } }, "additionalProperties": false }, "contentVersion": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "description", "documentCount", "status", "chunkConfig", "contentVersion", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "kb_123", "name": "knowledge bases", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:read", "details": { "requiredScope": "knowledge-bases:read", "routeId": "knowledgeBases.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:read", "Knowledge Bases"], "summary": "List knowledge bases", "description": "List knowledge bases.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBases.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/knowledge-bases?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "post": { "operationId": "knowledgeBases.create", "x-api-key-required-scope": "knowledge-bases:write", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBases.create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 } }, "required": ["name"] }, "examples": { "default": { "summary": "Create knowledge bases request", "value": { "name": "Partner support", "description": "Used by the partner integration." } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "documentCount": { "type": "number" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "chunkConfig": { "type": "object", "properties": { "maxChunkChars": { "type": "number" }, "minChunkChars": { "type": "number" }, "overlapSentences": { "type": "number" }, "splitThreshold": { "type": "number" } }, "additionalProperties": false }, "contentVersion": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "description", "documentCount", "status", "chunkConfig", "contentVersion", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_123", "name": "knowledge bases", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:write", "details": { "requiredScope": "knowledge-bases:write", "routeId": "knowledgeBases.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:write", "Knowledge Bases"], "summary": "Create knowledge bases", "description": "Create knowledge bases.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBases.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/knowledge-bases\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/knowledge-bases/{id}": { "get": { "operationId": "knowledgeBases.get", "x-api-key-required-scope": "knowledge-bases:read", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBases.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "documentCount": { "type": "number" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "chunkConfig": { "type": "object", "properties": { "maxChunkChars": { "type": "number" }, "minChunkChars": { "type": "number" }, "overlapSentences": { "type": "number" }, "splitThreshold": { "type": "number" } }, "additionalProperties": false }, "contentVersion": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "description", "documentCount", "status", "chunkConfig", "contentVersion", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:read", "details": { "requiredScope": "knowledge-bases:read", "routeId": "knowledgeBases.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:read", "Knowledge Bases"], "summary": "Get knowledge bases", "description": "Get knowledge bases.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBases.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/knowledge-bases/kb_123?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "patch": { "operationId": "knowledgeBases.update", "x-api-key-required-scope": "knowledge-bases:write", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBases.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": ["string", "null"], "maxLength": 1000 }, "chunkConfig": { "type": "object", "properties": { "maxChunkChars": { "type": "integer", "minimum": 200, "maximum": 6000 }, "minChunkChars": { "type": "integer", "minimum": 50, "maximum": 2000 }, "overlapSentences": { "type": "integer", "minimum": 0, "maximum": 5 }, "splitThreshold": { "type": "number", "minimum": 0, "maximum": 1 } } } } }, "examples": { "default": { "summary": "Update knowledge bases request", "value": { "name": "Partner support", "description": "Used by the partner integration.", "chunkConfig": { "maxChunkChars": 200, "minChunkChars": 50, "overlapSentences": 0, "splitThreshold": 0 } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "documentCount": { "type": "number" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "chunkConfig": { "type": "object", "properties": { "maxChunkChars": { "type": "number" }, "minChunkChars": { "type": "number" }, "overlapSentences": { "type": "number" }, "splitThreshold": { "type": "number" } }, "additionalProperties": false }, "contentVersion": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "description", "documentCount", "status", "chunkConfig", "contentVersion", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:write", "details": { "requiredScope": "knowledge-bases:write", "routeId": "knowledgeBases.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:write", "Knowledge Bases"], "summary": "Update knowledge bases", "description": "Update knowledge bases.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBases.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/knowledge-bases/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "knowledgeBases.delete", "x-api-key-required-scope": "knowledge-bases:write", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBases.delete", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:write", "details": { "requiredScope": "knowledge-bases:write", "routeId": "knowledgeBases.delete" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:write", "Knowledge Bases"], "summary": "Delete knowledge bases", "description": "Delete knowledge bases.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBases.delete`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/knowledge-bases/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/knowledge-bases/{id}/documents": { "get": { "operationId": "knowledgeBaseDocuments.list", "x-api-key-required-scope": "knowledge-bases:read", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBaseDocuments.list", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": ["qa_pair", "text_chunk"] }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": "string", "maxLength": 500 }, "required": false, "name": "search", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "knowledgeBaseId": { "type": "string" }, "type": { "type": "string", "enum": ["qa_pair", "text_chunk"] }, "question": { "type": ["string", "null"] }, "content": { "type": "string" }, "source": { "type": ["string", "null"] }, "category": { "type": ["string", "null"] }, "chunkIndex": { "type": ["number", "null"] }, "esSynced": { "type": "boolean" }, "embeddingSynced": { "type": "boolean" }, "version": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "knowledgeBaseId", "type", "question", "content", "source", "category", "chunkIndex", "esSynced", "embeddingSynced", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "kb_123", "name": "documents", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:read", "details": { "requiredScope": "knowledge-bases:read", "routeId": "knowledgeBaseDocuments.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:read", "Knowledge Bases"], "summary": "Get documents", "description": "Get documents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBaseDocuments.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "post": { "operationId": "knowledgeBaseDocuments.create", "x-api-key-required-scope": "knowledge-bases:write", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBaseDocuments.create", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1 }, "answer": { "type": "string", "minLength": 1 }, "source": { "type": "string" }, "category": { "type": "string" } }, "required": ["question", "answer"] }, "examples": { "default": { "summary": "Create documents request", "value": { "question": "What are your support hours?", "answer": "Support is available on weekdays from 09:00 to 18:00 JST.", "source": "partner_faq", "category": "support" } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "knowledgeBaseId": { "type": "string" }, "type": { "type": "string", "enum": ["qa_pair", "text_chunk"] }, "question": { "type": ["string", "null"] }, "content": { "type": "string" }, "source": { "type": ["string", "null"] }, "category": { "type": ["string", "null"] }, "chunkIndex": { "type": ["number", "null"] }, "esSynced": { "type": "boolean" }, "embeddingSynced": { "type": "boolean" }, "version": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "knowledgeBaseId", "type", "question", "content", "source", "category", "chunkIndex", "esSynced", "embeddingSynced", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_123", "name": "documents", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:write", "details": { "requiredScope": "knowledge-bases:write", "routeId": "knowledgeBaseDocuments.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:write", "Knowledge Bases"], "summary": "Create documents", "description": "Create documents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBaseDocuments.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/knowledge-bases/{id}/documents/{docId}": { "patch": { "operationId": "knowledgeBaseDocuments.update", "x-api-key-required-scope": "knowledge-bases:write", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBaseDocuments.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "docId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 }, "category": { "type": ["string", "null"] } } }, "examples": { "default": { "summary": "Update documents request", "value": { "question": "What are your support hours?", "content": "Support is available on weekdays from 09:00 to 18:00 JST.", "category": "example" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "knowledgeBaseId": { "type": "string" }, "type": { "type": "string", "enum": ["qa_pair", "text_chunk"] }, "question": { "type": ["string", "null"] }, "content": { "type": "string" }, "source": { "type": ["string", "null"] }, "category": { "type": ["string", "null"] }, "chunkIndex": { "type": ["number", "null"] }, "esSynced": { "type": "boolean" }, "embeddingSynced": { "type": "boolean" }, "version": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "knowledgeBaseId", "type", "question", "content", "source", "category", "chunkIndex", "esSynced", "embeddingSynced", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:write", "details": { "requiredScope": "knowledge-bases:write", "routeId": "knowledgeBaseDocuments.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:write", "Knowledge Bases"], "summary": "Update documents", "description": "Update documents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBaseDocuments.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents/doc_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "knowledgeBaseDocuments.delete", "x-api-key-required-scope": "knowledge-bases:write", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBaseDocuments.delete", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "docId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:write", "details": { "requiredScope": "knowledge-bases:write", "routeId": "knowledgeBaseDocuments.delete" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:write", "Knowledge Bases"], "summary": "Delete documents", "description": "Delete documents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBaseDocuments.delete`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents/doc_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/knowledge-bases/{id}/documents/delete-all": { "post": { "operationId": "knowledgeBaseDocuments.deleteAll", "x-api-key-required-scope": "knowledge-bases:write", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBaseDocuments.deleteAll", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deletedCount": { "type": "number" } }, "required": ["deletedCount"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:write", "details": { "requiredScope": "knowledge-bases:write", "routeId": "knowledgeBaseDocuments.deleteAll" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:write", "Knowledge Bases"], "summary": "Delete all documents", "description": "Delete all documents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBaseDocuments.deleteAll`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents/delete-all\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/knowledge-bases/{id}/documents/{docId}/versions": { "get": { "operationId": "knowledgeBaseDocumentVersions.list", "x-api-key-required-scope": "knowledge-bases:read", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBaseDocumentVersions.list", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "docId", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "documentId": { "type": "string" }, "knowledgeBaseId": { "type": "string" }, "version": { "type": "number" }, "snapshot": { "type": "object", "properties": { "type": { "type": "string" }, "question": { "type": ["string", "null"] }, "content": { "type": "string" }, "source": { "type": ["string", "null"] }, "category": { "type": ["string", "null"] }, "chunkIndex": { "type": ["number", "null"] } }, "required": [ "type", "question", "content", "source", "category", "chunkIndex" ], "additionalProperties": false }, "changeType": { "type": "string", "enum": ["created", "updated", "deleted"] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "documentId", "knowledgeBaseId", "version", "snapshot", "changeType", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "kb_123", "name": "versions", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:read", "details": { "requiredScope": "knowledge-bases:read", "routeId": "knowledgeBaseDocumentVersions.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:read", "Knowledge Bases"], "summary": "Get versions", "description": "Get versions.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBaseDocumentVersions.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents/doc_123/versions?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/knowledge-bases/{id}/documents/{docId}/rollback": { "post": { "operationId": "knowledgeBaseDocuments.rollback", "x-api-key-required-scope": "knowledge-bases:write", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBaseDocuments.rollback", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "docId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "knowledgeBaseId": { "type": "string" }, "type": { "type": "string", "enum": ["qa_pair", "text_chunk"] }, "question": { "type": ["string", "null"] }, "content": { "type": "string" }, "source": { "type": ["string", "null"] }, "category": { "type": ["string", "null"] }, "chunkIndex": { "type": ["number", "null"] }, "esSynced": { "type": "boolean" }, "embeddingSynced": { "type": "boolean" }, "version": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "knowledgeBaseId", "type", "question", "content", "source", "category", "chunkIndex", "esSynced", "embeddingSynced", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "kb_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:write", "details": { "requiredScope": "knowledge-bases:write", "routeId": "knowledgeBaseDocuments.rollback" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:write", "Knowledge Bases"], "summary": "Rollback document", "description": "Rollback document.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBaseDocuments.rollback`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents/doc_123/rollback\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/knowledge-bases/{id}/sync-status": { "get": { "operationId": "knowledgeBases.getSyncStatus", "x-api-key-required-scope": "knowledge-bases:read", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBases.getSyncStatus", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": ["object", "null"], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "totalDocuments": { "type": "number" }, "syncedDocuments": { "type": "number" }, "failedDocuments": { "type": "number" }, "errorMessage": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "totalDocuments", "syncedDocuments", "failedDocuments", "errorMessage", "createdAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "kb_123", "name": "sync status", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:read", "details": { "requiredScope": "knowledge-bases:read", "routeId": "knowledgeBases.getSyncStatus" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:read", "Knowledge Bases"], "summary": "List sync status", "description": "List sync status.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBases.getSyncStatus`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/sync-status?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/knowledge-bases/{id}/analytics": { "get": { "operationId": "knowledgeBaseAnalytics.get", "x-api-key-required-scope": "knowledge-bases:read", "x-api-key-risk-class": "standard", "x-route-id": "knowledgeBaseAnalytics.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {} }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "kb_123", "name": "analytics", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: knowledge-bases:read", "details": { "requiredScope": "knowledge-bases:read", "routeId": "knowledgeBaseAnalytics.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: knowledge-bases:read", "Knowledge Bases"], "summary": "List analytics", "description": "List analytics.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBaseAnalytics.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/analytics?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/entity-indexes": { "get": { "operationId": "entityIndexes.list", "x-api-key-required-scope": "entity-indexes:read", "x-api-key-risk-class": "standard", "x-route-id": "entityIndexes.list", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "entityType": { "type": "string" }, "meiliIndexName": { "type": "string" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "schemaFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": ["string", "number", "boolean", "array"] }, "required": { "type": "boolean" } }, "required": ["name", "type", "required"], "additionalProperties": false } }, "searchableFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "boost": { "type": "number" }, "fuzzy": { "type": "boolean" } }, "required": ["name", "boost", "fuzzy"], "additionalProperties": false } }, "returnFields": { "type": "array", "items": { "type": "string" } }, "queryPrompt": { "type": ["string", "null"] }, "maxResults": { "type": "number" }, "minScore": { "type": "number" }, "documentCount": { "type": "number" }, "lastSyncedAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "slug", "name", "description", "entityType", "meiliIndexName", "status", "schemaFields", "searchableFields", "returnFields", "queryPrompt", "maxResults", "minScore", "documentCount", "lastSyncedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "idx_123", "name": "entity indexes", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:read", "details": { "requiredScope": "entity-indexes:read", "routeId": "entityIndexes.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:read", "Entity Indexes"], "summary": "List entity indexes", "description": "List entity indexes.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:read`. Risk class: `standard`. Route ID: `entityIndexes.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/entity-indexes?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "post": { "operationId": "entityIndexes.create", "x-api-key-required-scope": "entity-indexes:write", "x-api-key-risk-class": "standard", "x-route-id": "entityIndexes.create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": ["string", "null"], "maxLength": 1000 }, "entityType": { "type": "string", "minLength": 1, "maxLength": 64 }, "schemaFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": ["string", "number", "boolean", "array"] }, "required": { "type": "boolean" } }, "required": ["name", "type", "required"] }, "minItems": 1 }, "searchableFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "boost": { "type": "number", "exclusiveMinimum": 0 }, "fuzzy": { "type": "boolean" } }, "required": ["name", "boost", "fuzzy"] }, "minItems": 1 }, "returnFields": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "queryPrompt": { "type": ["string", "null"], "maxLength": 2000 }, "maxResults": { "type": "integer", "exclusiveMinimum": 0 }, "minScore": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "slug", "name", "description", "entityType", "schemaFields", "searchableFields", "returnFields", "queryPrompt", "maxResults", "minScore" ] }, "examples": { "default": { "summary": "Create entity indexes request", "value": { "slug": "customers", "name": "Customers", "description": "CRM customer lookup data.", "entityType": "customer", "schemaFields": [ { "name": "email", "type": "string", "required": true } ], "searchableFields": [ { "name": "email", "boost": 1, "fuzzy": false } ], "returnFields": ["email", "name"], "queryPrompt": "Find customer records by email address or customer name.", "maxResults": 5, "minScore": 0.7 } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "entityType": { "type": "string" }, "meiliIndexName": { "type": "string" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "schemaFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": ["string", "number", "boolean", "array"] }, "required": { "type": "boolean" } }, "required": ["name", "type", "required"], "additionalProperties": false } }, "searchableFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "boost": { "type": "number" }, "fuzzy": { "type": "boolean" } }, "required": ["name", "boost", "fuzzy"], "additionalProperties": false } }, "returnFields": { "type": "array", "items": { "type": "string" } }, "queryPrompt": { "type": ["string", "null"] }, "maxResults": { "type": "number" }, "minScore": { "type": "number" }, "documentCount": { "type": "number" }, "lastSyncedAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "slug", "name", "description", "entityType", "meiliIndexName", "status", "schemaFields", "searchableFields", "returnFields", "queryPrompt", "maxResults", "minScore", "documentCount", "lastSyncedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "idx_123", "name": "entity indexes", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:write", "details": { "requiredScope": "entity-indexes:write", "routeId": "entityIndexes.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:write", "Entity Indexes"], "summary": "Create entity indexes", "description": "Create entity indexes.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityIndexes.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/entity-indexes\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/entity-indexes/{id}": { "get": { "operationId": "entityIndexes.get", "x-api-key-required-scope": "entity-indexes:read", "x-api-key-risk-class": "standard", "x-route-id": "entityIndexes.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "entityType": { "type": "string" }, "meiliIndexName": { "type": "string" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "schemaFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": ["string", "number", "boolean", "array"] }, "required": { "type": "boolean" } }, "required": ["name", "type", "required"], "additionalProperties": false } }, "searchableFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "boost": { "type": "number" }, "fuzzy": { "type": "boolean" } }, "required": ["name", "boost", "fuzzy"], "additionalProperties": false } }, "returnFields": { "type": "array", "items": { "type": "string" } }, "queryPrompt": { "type": ["string", "null"] }, "maxResults": { "type": "number" }, "minScore": { "type": "number" }, "documentCount": { "type": "number" }, "lastSyncedAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "slug", "name", "description", "entityType", "meiliIndexName", "status", "schemaFields", "searchableFields", "returnFields", "queryPrompt", "maxResults", "minScore", "documentCount", "lastSyncedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "idx_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:read", "details": { "requiredScope": "entity-indexes:read", "routeId": "entityIndexes.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:read", "Entity Indexes"], "summary": "Get entity indexes", "description": "Get entity indexes.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:read`. Risk class: `standard`. Route ID: `entityIndexes.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/entity-indexes/kb_123?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "patch": { "operationId": "entityIndexes.update", "x-api-key-required-scope": "entity-indexes:write", "x-api-key-risk-class": "standard", "x-route-id": "entityIndexes.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": ["string", "null"], "maxLength": 1000 }, "entityType": { "type": "string", "minLength": 1, "maxLength": 64 }, "schemaFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": ["string", "number", "boolean", "array"] }, "required": { "type": "boolean" } }, "required": ["name", "type", "required"] }, "minItems": 1 }, "searchableFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "boost": { "type": "number", "exclusiveMinimum": 0 }, "fuzzy": { "type": "boolean" } }, "required": ["name", "boost", "fuzzy"] }, "minItems": 1 }, "returnFields": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "queryPrompt": { "type": ["string", "null"], "maxLength": 2000 }, "maxResults": { "type": "integer", "exclusiveMinimum": 0 }, "minScore": { "type": "number", "minimum": 0, "maximum": 1 } } }, "examples": { "default": { "summary": "Update entity indexes request", "value": { "name": "Partner support", "description": "Used by the partner integration.", "entityType": "example", "schemaFields": [ { "name": "Partner support", "type": "string", "required": true } ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "entityType": { "type": "string" }, "meiliIndexName": { "type": "string" }, "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "schemaFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": ["string", "number", "boolean", "array"] }, "required": { "type": "boolean" } }, "required": ["name", "type", "required"], "additionalProperties": false } }, "searchableFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "boost": { "type": "number" }, "fuzzy": { "type": "boolean" } }, "required": ["name", "boost", "fuzzy"], "additionalProperties": false } }, "returnFields": { "type": "array", "items": { "type": "string" } }, "queryPrompt": { "type": ["string", "null"] }, "maxResults": { "type": "number" }, "minScore": { "type": "number" }, "documentCount": { "type": "number" }, "lastSyncedAt": { "type": ["string", "null"], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "slug", "name", "description", "entityType", "meiliIndexName", "status", "schemaFields", "searchableFields", "returnFields", "queryPrompt", "maxResults", "minScore", "documentCount", "lastSyncedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "idx_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:write", "details": { "requiredScope": "entity-indexes:write", "routeId": "entityIndexes.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:write", "Entity Indexes"], "summary": "Update entity indexes", "description": "Update entity indexes.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityIndexes.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/entity-indexes/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "entityIndexes.delete", "x-api-key-required-scope": "entity-indexes:write", "x-api-key-risk-class": "standard", "x-route-id": "entityIndexes.delete", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:write", "details": { "requiredScope": "entity-indexes:write", "routeId": "entityIndexes.delete" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:write", "Entity Indexes"], "summary": "Delete entity indexes", "description": "Delete entity indexes.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityIndexes.delete`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/entity-indexes/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/entity-indexes/{id}/sync-status": { "get": { "operationId": "entityIndexes.getSyncStatus", "x-api-key-required-scope": "entity-indexes:read", "x-api-key-risk-class": "standard", "x-route-id": "entityIndexes.getSyncStatus", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["ready", "processing", "error"] }, "documentCount": { "type": "number" }, "pendingJobs": { "type": "number" }, "lastSyncedAt": { "type": ["string", "null"], "format": "date-time" } }, "required": ["status", "documentCount", "pendingJobs", "lastSyncedAt"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "idx_123", "name": "sync status", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:read", "details": { "requiredScope": "entity-indexes:read", "routeId": "entityIndexes.getSyncStatus" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:read", "Entity Indexes"], "summary": "List sync status", "description": "List sync status.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:read`. Risk class: `standard`. Route ID: `entityIndexes.getSyncStatus`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/entity-indexes/kb_123/sync-status?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/entity-indexes/{id}/documents": { "get": { "operationId": "entityDocuments.list", "x-api-key-required-scope": "entity-indexes:read", "x-api-key-risk-class": "standard", "x-route-id": "entityDocuments.list", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "maxLength": 500 }, "required": false, "name": "search", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "entityIndexId": { "type": "string" }, "externalId": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "syncStatus": { "type": "string", "enum": ["pending", "synced", "error"] }, "syncError": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "entityIndexId", "externalId", "data", "syncStatus", "syncError", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "idx_123", "name": "documents", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:read", "details": { "requiredScope": "entity-indexes:read", "routeId": "entityDocuments.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:read", "Entity Indexes"], "summary": "Get documents", "description": "Get documents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:read`. Risk class: `standard`. Route ID: `entityDocuments.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "post": { "operationId": "entityDocuments.create", "x-api-key-required-scope": "entity-indexes:write", "x-api-key-risk-class": "standard", "x-route-id": "entityDocuments.create", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "externalId": { "type": ["string", "null"], "minLength": 1 }, "data": { "type": "object", "additionalProperties": {} } }, "required": ["data"] }, "examples": { "default": { "summary": "Create documents request", "value": { "data": { "key": "value" }, "externalId": "external_123" } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "entityIndexId": { "type": "string" }, "externalId": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "syncStatus": { "type": "string", "enum": ["pending", "synced", "error"] }, "syncError": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "entityIndexId", "externalId", "data", "syncStatus", "syncError", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "idx_123", "name": "documents", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:write", "details": { "requiredScope": "entity-indexes:write", "routeId": "entityDocuments.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:write", "Entity Indexes"], "summary": "Create documents", "description": "Create documents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityDocuments.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/entity-indexes/{id}/documents/delete-all": { "post": { "operationId": "entityDocuments.deleteAll", "x-api-key-required-scope": "entity-indexes:write", "x-api-key-risk-class": "standard", "x-route-id": "entityDocuments.deleteAll", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deletedCount": { "type": "number" } }, "required": ["deletedCount"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "idx_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:write", "details": { "requiredScope": "entity-indexes:write", "routeId": "entityDocuments.deleteAll" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:write", "Entity Indexes"], "summary": "Delete all documents", "description": "Delete all documents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityDocuments.deleteAll`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents/delete-all\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/entity-indexes/{id}/documents/import": { "post": { "operationId": "entityDocuments.import", "x-api-key-required-scope": "entity-indexes:write", "x-api-key-risk-class": "standard", "x-route-id": "entityDocuments.import", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": ["csv", "json"] }, "body": { "type": "string" }, "mapping": { "type": ["object", "null"], "additionalProperties": { "type": "string" } } }, "required": ["format", "body"] }, "examples": { "default": { "summary": "Import documents request", "value": { "format": "csv", "body": "external_id,name\ncust_123,Example Customer\n", "mapping": { "key": "value" } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "inserted": { "type": "number" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "rowIndex": { "type": "number" }, "message": { "type": "string" } }, "required": ["rowIndex", "message"], "additionalProperties": false } } }, "required": ["inserted", "errors"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "idx_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:write", "details": { "requiredScope": "entity-indexes:write", "routeId": "entityDocuments.import" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:write", "Entity Indexes"], "summary": "Import documents", "description": "Import documents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityDocuments.import`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents/import\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/entity-indexes/{id}/documents/{docId}": { "get": { "operationId": "entityDocuments.get", "x-api-key-required-scope": "entity-indexes:read", "x-api-key-risk-class": "standard", "x-route-id": "entityDocuments.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "docId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "entityIndexId": { "type": "string" }, "externalId": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "syncStatus": { "type": "string", "enum": ["pending", "synced", "error"] }, "syncError": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "entityIndexId", "externalId", "data", "syncStatus", "syncError", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "idx_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:read", "details": { "requiredScope": "entity-indexes:read", "routeId": "entityDocuments.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:read", "Entity Indexes"], "summary": "Get documents", "description": "Get documents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:read`. Risk class: `standard`. Route ID: `entityDocuments.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents/doc_123?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "patch": { "operationId": "entityDocuments.update", "x-api-key-required-scope": "entity-indexes:write", "x-api-key-risk-class": "standard", "x-route-id": "entityDocuments.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "docId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} } }, "required": ["data"] }, "examples": { "default": { "summary": "Update documents request", "value": { "data": { "key": "value" } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "entityIndexId": { "type": "string" }, "externalId": { "type": "string" }, "data": { "type": "object", "additionalProperties": true }, "syncStatus": { "type": "string", "enum": ["pending", "synced", "error"] }, "syncError": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "entityIndexId", "externalId", "data", "syncStatus", "syncError", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "idx_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:write", "details": { "requiredScope": "entity-indexes:write", "routeId": "entityDocuments.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:write", "Entity Indexes"], "summary": "Update documents", "description": "Update documents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityDocuments.update`.\n\nExample:\n\n```sh\ncurl -sS -X PATCH \"https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents/doc_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "entityDocuments.delete", "x-api-key-required-scope": "entity-indexes:write", "x-api-key-risk-class": "standard", "x-route-id": "entityDocuments.delete", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "docId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": ["success"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: entity-indexes:write", "details": { "requiredScope": "entity-indexes:write", "routeId": "entityDocuments.delete" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: entity-indexes:write", "Entity Indexes"], "summary": "Delete documents", "description": "Delete documents.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityDocuments.delete`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents/doc_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/post-call-actions": { "get": { "operationId": "postCallActions.list", "x-api-key-required-scope": "post-call-actions:read", "x-api-key-risk-class": "standard", "x-route-id": "postCallActions.list", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["call.ended"] }, "isActive": { "type": "boolean" }, "conditions": { "type": "object", "properties": { "combinator": { "type": "string", "enum": ["AND", "OR"] }, "children": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": ["combinator", "children"] }, "actionType": { "type": "string", "enum": ["email", "sms"] }, "actionPayload": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["email"] }, "recipients": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } } }, "required": ["to", "cc", "bcc"], "additionalProperties": false }, "subjectTemplate": { "type": "string" }, "bodyTemplate": { "type": "string" }, "bodyFormat": { "type": "string", "enum": ["html", "text"] } }, "required": [ "type", "recipients", "subjectTemplate", "bodyTemplate", "bodyFormat" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["sms"] }, "recipients": { "type": "array", "items": { "type": "string" } }, "bodyTemplate": { "type": "string" }, "fromNumber": { "type": "string" } }, "required": ["type", "recipients", "bodyTemplate"], "additionalProperties": false } ] }, "llmFallbackOnError": { "type": "string", "enum": ["skip", "execute"] }, "llmTimeoutMs": { "type": "number" }, "createdBy": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "description", "trigger", "isActive", "conditions", "actionType", "actionPayload", "llmFallbackOnError", "llmTimeoutMs", "createdBy", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "pca_123", "name": "post-call actions", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: post-call-actions:read", "details": { "requiredScope": "post-call-actions:read", "routeId": "postCallActions.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: post-call-actions:read", "Post-Call Actions"], "summary": "List post-call actions", "description": "List post-call actions.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `post-call-actions:read`. Risk class: `standard`. Route ID: `postCallActions.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/post-call-actions?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "post": { "operationId": "postCallActions.create", "x-api-key-required-scope": "post-call-actions:write", "x-api-key-risk-class": "standard", "x-route-id": "postCallActions.create", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": ["string", "null"], "maxLength": 500 }, "isActive": { "type": "boolean" }, "conditions": { "type": "object", "properties": { "combinator": { "type": "string", "enum": ["AND", "OR"] }, "children": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 20 } }, "required": ["combinator", "children"] }, "actionType": { "type": "string", "enum": ["email", "sms"] }, "actionPayload": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["email"] }, "recipients": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 50 }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50 }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50 } }, "required": ["to", "cc", "bcc"] }, "subjectTemplate": { "type": "string", "minLength": 1, "maxLength": 200 }, "bodyTemplate": { "type": "string", "minLength": 1, "maxLength": 20000 }, "bodyFormat": { "type": "string", "enum": ["html", "text"] } }, "required": [ "type", "recipients", "subjectTemplate", "bodyTemplate", "bodyFormat" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["sms"] }, "recipients": { "type": "array", "items": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "minItems": 1, "maxItems": 20 }, "bodyTemplate": { "type": "string", "minLength": 1, "maxLength": 1600 }, "fromNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" } }, "required": ["type", "recipients", "bodyTemplate"] } ] }, "llmFallbackOnError": { "type": "string", "enum": ["skip", "execute"], "default": "skip" }, "llmTimeoutMs": { "type": "integer", "minimum": 5000, "maximum": 120000 } }, "required": ["name", "conditions", "actionType", "actionPayload"] }, "examples": { "default": { "summary": "Create post-call actions request", "value": { "name": "Send missed-call summary", "description": "Email support when a caller asks for a follow-up.", "isActive": true, "conditions": { "combinator": "AND", "children": [ { "kind": "preset", "key": "call_ended", "value": true } ] }, "actionType": "email", "actionPayload": { "type": "email", "recipients": { "to": ["ops@example.com"], "cc": [], "bcc": [] }, "subjectTemplate": "VoiceAgent follow-up for {{call.id}}", "bodyTemplate": "Caller summary: {{call.summary}}", "bodyFormat": "text" }, "llmFallbackOnError": "skip" } } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["call.ended"] }, "isActive": { "type": "boolean" }, "conditions": { "type": "object", "properties": { "combinator": { "type": "string", "enum": ["AND", "OR"] }, "children": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": ["combinator", "children"] }, "actionType": { "type": "string", "enum": ["email", "sms"] }, "actionPayload": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["email"] }, "recipients": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } } }, "required": ["to", "cc", "bcc"], "additionalProperties": false }, "subjectTemplate": { "type": "string" }, "bodyTemplate": { "type": "string" }, "bodyFormat": { "type": "string", "enum": ["html", "text"] } }, "required": [ "type", "recipients", "subjectTemplate", "bodyTemplate", "bodyFormat" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["sms"] }, "recipients": { "type": "array", "items": { "type": "string" } }, "bodyTemplate": { "type": "string" }, "fromNumber": { "type": "string" } }, "required": ["type", "recipients", "bodyTemplate"], "additionalProperties": false } ] }, "llmFallbackOnError": { "type": "string", "enum": ["skip", "execute"] }, "llmTimeoutMs": { "type": "number" }, "createdBy": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "description", "trigger", "isActive", "conditions", "actionType", "actionPayload", "llmFallbackOnError", "llmTimeoutMs", "createdBy", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "pca_123", "name": "post-call actions", "createdAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: post-call-actions:write", "details": { "requiredScope": "post-call-actions:write", "routeId": "postCallActions.create" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: post-call-actions:write", "Post-Call Actions"], "summary": "Create post-call actions", "description": "Create post-call actions.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `post-call-actions:write`. Risk class: `standard`. Route ID: `postCallActions.create`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/post-call-actions\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/post-call-actions/schema/variables": { "get": { "operationId": "postCallActions.getSchemaVariables", "x-api-key-required-scope": "post-call-actions:read", "x-api-key-risk-class": "standard", "x-route-id": "postCallActions.getSchemaVariables", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "variables": { "type": "array", "items": { "type": "string" } }, "dynamic": { "type": "boolean" } }, "required": ["key", "label", "variables"], "additionalProperties": false } } }, "required": ["categories"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "pca_123", "name": "variables", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: post-call-actions:read", "details": { "requiredScope": "post-call-actions:read", "routeId": "postCallActions.getSchemaVariables" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: post-call-actions:read", "Post-Call Actions"], "summary": "List variables", "description": "List variables.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `post-call-actions:read`. Risk class: `standard`. Route ID: `postCallActions.getSchemaVariables`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/post-call-actions/schema/variables?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/post-call-actions/{id}": { "get": { "operationId": "postCallActions.get", "x-api-key-required-scope": "post-call-actions:read", "x-api-key-risk-class": "standard", "x-route-id": "postCallActions.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["call.ended"] }, "isActive": { "type": "boolean" }, "conditions": { "type": "object", "properties": { "combinator": { "type": "string", "enum": ["AND", "OR"] }, "children": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": ["combinator", "children"] }, "actionType": { "type": "string", "enum": ["email", "sms"] }, "actionPayload": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["email"] }, "recipients": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } } }, "required": ["to", "cc", "bcc"], "additionalProperties": false }, "subjectTemplate": { "type": "string" }, "bodyTemplate": { "type": "string" }, "bodyFormat": { "type": "string", "enum": ["html", "text"] } }, "required": [ "type", "recipients", "subjectTemplate", "bodyTemplate", "bodyFormat" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["sms"] }, "recipients": { "type": "array", "items": { "type": "string" } }, "bodyTemplate": { "type": "string" }, "fromNumber": { "type": "string" } }, "required": ["type", "recipients", "bodyTemplate"], "additionalProperties": false } ] }, "llmFallbackOnError": { "type": "string", "enum": ["skip", "execute"] }, "llmTimeoutMs": { "type": "number" }, "createdBy": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "description", "trigger", "isActive", "conditions", "actionType", "actionPayload", "llmFallbackOnError", "llmTimeoutMs", "createdBy", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "pca_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: post-call-actions:read", "details": { "requiredScope": "post-call-actions:read", "routeId": "postCallActions.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: post-call-actions:read", "Post-Call Actions"], "summary": "Get post-call actions", "description": "Get post-call actions.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `post-call-actions:read`. Risk class: `standard`. Route ID: `postCallActions.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/post-call-actions/kb_123?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "put": { "operationId": "postCallActions.update", "x-api-key-required-scope": "post-call-actions:write", "x-api-key-risk-class": "standard", "x-route-id": "postCallActions.update", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": ["string", "null"], "maxLength": 500 }, "isActive": { "type": "boolean" }, "conditions": { "type": "object", "properties": { "combinator": { "type": "string", "enum": ["AND", "OR"] }, "children": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "maxItems": 20 } }, "required": ["combinator", "children"] }, "actionType": { "type": "string", "enum": ["email", "sms"] }, "actionPayload": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["email"] }, "recipients": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 50 }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50 }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50 } }, "required": ["to", "cc", "bcc"] }, "subjectTemplate": { "type": "string", "minLength": 1, "maxLength": 200 }, "bodyTemplate": { "type": "string", "minLength": 1, "maxLength": 20000 }, "bodyFormat": { "type": "string", "enum": ["html", "text"] } }, "required": [ "type", "recipients", "subjectTemplate", "bodyTemplate", "bodyFormat" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["sms"] }, "recipients": { "type": "array", "items": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "minItems": 1, "maxItems": 20 }, "bodyTemplate": { "type": "string", "minLength": 1, "maxLength": 1600 }, "fromNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" } }, "required": ["type", "recipients", "bodyTemplate"] } ] }, "llmFallbackOnError": { "type": "string", "enum": ["skip", "execute"], "default": "skip" }, "llmTimeoutMs": { "type": "integer", "minimum": 5000, "maximum": 120000 } } }, "examples": { "default": { "summary": "Replace post-call actions request", "value": { "name": "Send missed-call summary", "description": "Email support when a caller asks for a follow-up.", "isActive": true, "conditions": { "combinator": "AND", "children": [ { "kind": "preset", "key": "call_ended", "value": true } ] }, "actionType": "email", "actionPayload": { "type": "email", "recipients": { "to": ["ops@example.com"], "cc": [], "bcc": [] }, "subjectTemplate": "VoiceAgent follow-up for {{call.id}}", "bodyTemplate": "Caller summary: {{call.summary}}", "bodyFormat": "text" }, "llmFallbackOnError": "skip" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["call.ended"] }, "isActive": { "type": "boolean" }, "conditions": { "type": "object", "properties": { "combinator": { "type": "string", "enum": ["AND", "OR"] }, "children": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": ["combinator", "children"] }, "actionType": { "type": "string", "enum": ["email", "sms"] }, "actionPayload": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["email"] }, "recipients": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } } }, "required": ["to", "cc", "bcc"], "additionalProperties": false }, "subjectTemplate": { "type": "string" }, "bodyTemplate": { "type": "string" }, "bodyFormat": { "type": "string", "enum": ["html", "text"] } }, "required": [ "type", "recipients", "subjectTemplate", "bodyTemplate", "bodyFormat" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["sms"] }, "recipients": { "type": "array", "items": { "type": "string" } }, "bodyTemplate": { "type": "string" }, "fromNumber": { "type": "string" } }, "required": ["type", "recipients", "bodyTemplate"], "additionalProperties": false } ] }, "llmFallbackOnError": { "type": "string", "enum": ["skip", "execute"] }, "llmTimeoutMs": { "type": "number" }, "createdBy": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "description", "trigger", "isActive", "conditions", "actionType", "actionPayload", "llmFallbackOnError", "llmTimeoutMs", "createdBy", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "pca_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: post-call-actions:write", "details": { "requiredScope": "post-call-actions:write", "routeId": "postCallActions.update" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: post-call-actions:write", "Post-Call Actions"], "summary": "Replace post-call actions", "description": "Replace post-call actions.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `post-call-actions:write`. Risk class: `standard`. Route ID: `postCallActions.update`.\n\nExample:\n\n```sh\ncurl -sS -X PUT \"https://api.voiceagent.example/api/v1/post-call-actions/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." }, "delete": { "operationId": "postCallActions.delete", "x-api-key-required-scope": "post-call-actions:write", "x-api-key-risk-class": "standard", "x-route-id": "postCallActions.delete", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": ["ok"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "success": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: post-call-actions:write", "details": { "requiredScope": "post-call-actions:write", "routeId": "postCallActions.delete" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: post-call-actions:write", "Post-Call Actions"], "summary": "Delete post-call actions", "description": "Delete post-call actions.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `post-call-actions:write`. Risk class: `standard`. Route ID: `postCallActions.delete`.\n\nExample:\n\n```sh\ncurl -sS -X DELETE \"https://api.voiceagent.example/api/v1/post-call-actions/kb_123\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/post-call-actions/{id}/toggle": { "post": { "operationId": "postCallActions.toggle", "x-api-key-required-scope": "post-call-actions:write", "x-api-key-risk-class": "standard", "x-route-id": "postCallActions.toggle", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "trigger": { "type": "string", "enum": ["call.ended"] }, "isActive": { "type": "boolean" }, "conditions": { "type": "object", "properties": { "combinator": { "type": "string", "enum": ["AND", "OR"] }, "children": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": ["combinator", "children"] }, "actionType": { "type": "string", "enum": ["email", "sms"] }, "actionPayload": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["email"] }, "recipients": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } } }, "required": ["to", "cc", "bcc"], "additionalProperties": false }, "subjectTemplate": { "type": "string" }, "bodyTemplate": { "type": "string" }, "bodyFormat": { "type": "string", "enum": ["html", "text"] } }, "required": [ "type", "recipients", "subjectTemplate", "bodyTemplate", "bodyFormat" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": ["sms"] }, "recipients": { "type": "array", "items": { "type": "string" } }, "bodyTemplate": { "type": "string" }, "fromNumber": { "type": "string" } }, "required": ["type", "recipients", "bodyTemplate"], "additionalProperties": false } ] }, "llmFallbackOnError": { "type": "string", "enum": ["skip", "execute"] }, "llmTimeoutMs": { "type": "number" }, "createdBy": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "name", "description", "trigger", "isActive", "conditions", "actionType", "actionPayload", "llmFallbackOnError", "llmTimeoutMs", "createdBy", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "pca_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: post-call-actions:write", "details": { "requiredScope": "post-call-actions:write", "routeId": "postCallActions.toggle" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: post-call-actions:write", "Post-Call Actions"], "summary": "Toggle post-call action", "description": "Toggle post-call action.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `post-call-actions:write`. Risk class: `standard`. Route ID: `postCallActions.toggle`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/post-call-actions/kb_123/toggle\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/post-call-actions/{id}/test": { "post": { "operationId": "postCallActions.test", "x-api-key-required-scope": "post-call-actions:execute", "x-api-key-risk-class": "high", "x-route-id": "postCallActions.test", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": ["latest_call", "dummy", "specific"] }, "callId": { "type": "string" } }, "required": ["mode"] }, "examples": { "default": { "summary": "Test post-call actions request", "value": { "mode": "specific", "callId": "call_123" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "renderedSubject": { "type": ["string", "null"] }, "renderedBody": { "type": "string" }, "providerMessageId": { "type": "string" } }, "required": ["renderedSubject", "renderedBody", "providerMessageId"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "pca_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: post-call-actions:execute", "details": { "requiredScope": "post-call-actions:execute", "routeId": "postCallActions.test" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: post-call-actions:execute", "Post-Call Actions"], "summary": "Test post-call actions", "description": "Test post-call actions.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `post-call-actions:execute`. Risk class: `high`. Route ID: `postCallActions.test`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/post-call-actions/kb_123/test\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/post-call-actions/{id}/execution-logs": { "get": { "operationId": "postCallActions.listExecutionLogs", "x-api-key-required-scope": "post-call-actions:read", "x-api-key-risk-class": "standard", "x-route-id": "postCallActions.listExecutionLogs", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": ["string", "null"] }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": ["string", "null"] }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "postCallActionId": { "type": ["string", "null"] }, "postCallActionSnapshot": { "type": "object", "additionalProperties": true }, "callId": { "type": "string" }, "recipient": { "type": ["string", "null"] }, "recipientIndex": { "type": "number" }, "status": { "type": "string", "enum": [ "pending", "evaluating_llm", "skipped", "queued", "sending", "sent", "retrying", "failed", "dead" ] }, "conditionResult": { "type": ["object", "null"], "properties": { "status": { "type": "string", "enum": ["true", "false"] }, "reason": { "type": "string" }, "llmResults": { "type": "object", "additionalProperties": { "type": "object", "properties": { "result": { "type": "boolean" }, "reason": { "type": "string" } }, "required": ["result", "reason"], "additionalProperties": false } } }, "required": ["status"], "additionalProperties": false }, "attemptCount": { "type": "number" }, "maxAttempts": { "type": "number" }, "nextAttemptAt": { "type": ["string", "null"], "format": "date-time" }, "providerMessageId": { "type": ["string", "null"] }, "renderedSubject": { "type": ["string", "null"] }, "renderedBody": { "type": ["string", "null"] }, "recipientsSnapshot": { "type": "object", "additionalProperties": true }, "lastError": { "type": ["string", "null"] }, "lastErrorAt": { "type": ["string", "null"], "format": "date-time" }, "errorHistory": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "number" }, "at": { "type": "string" }, "error": { "type": "string" } }, "required": ["attempt", "at", "error"], "additionalProperties": false } }, "currentJobId": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "postCallActionId", "postCallActionSnapshot", "callId", "recipient", "recipientIndex", "status", "conditionResult", "attemptCount", "maxAttempts", "nextAttemptAt", "providerMessageId", "renderedSubject", "renderedBody", "recipientsSnapshot", "lastError", "lastErrorAt", "errorHistory", "currentJobId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "log_123", "name": "execution logs", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: post-call-actions:read", "details": { "requiredScope": "post-call-actions:read", "routeId": "postCallActions.listExecutionLogs" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: post-call-actions:read", "Action Execution Logs"], "summary": "Get execution logs", "description": "Get execution logs.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `post-call-actions:read`. Risk class: `standard`. Route ID: `postCallActions.listExecutionLogs`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/post-call-actions/kb_123/execution-logs?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/action-execution-logs": { "get": { "operationId": "actionExecutionLogs.list", "x-api-key-required-scope": "post-call-actions:read", "x-api-key-risk-class": "standard", "x-route-id": "actionExecutionLogs.list", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "postCallActionId", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "callId", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": ["string", "null"] }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": ["string", "null"] }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500 }, "required": false, "name": "q", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "postCallActionId": { "type": ["string", "null"] }, "postCallActionSnapshot": { "type": "object", "additionalProperties": true }, "callId": { "type": "string" }, "recipient": { "type": ["string", "null"] }, "recipientIndex": { "type": "number" }, "status": { "type": "string", "enum": [ "pending", "evaluating_llm", "skipped", "queued", "sending", "sent", "retrying", "failed", "dead" ] }, "conditionResult": { "type": ["object", "null"], "properties": { "status": { "type": "string", "enum": ["true", "false"] }, "reason": { "type": "string" }, "llmResults": { "type": "object", "additionalProperties": { "type": "object", "properties": { "result": { "type": "boolean" }, "reason": { "type": "string" } }, "required": ["result", "reason"], "additionalProperties": false } } }, "required": ["status"], "additionalProperties": false }, "attemptCount": { "type": "number" }, "maxAttempts": { "type": "number" }, "nextAttemptAt": { "type": ["string", "null"], "format": "date-time" }, "providerMessageId": { "type": ["string", "null"] }, "renderedSubject": { "type": ["string", "null"] }, "renderedBody": { "type": ["string", "null"] }, "recipientsSnapshot": { "type": "object", "additionalProperties": true }, "lastError": { "type": ["string", "null"] }, "lastErrorAt": { "type": ["string", "null"], "format": "date-time" }, "errorHistory": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "number" }, "at": { "type": "string" }, "error": { "type": "string" } }, "required": ["attempt", "at", "error"], "additionalProperties": false } }, "currentJobId": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "postCallActionId", "postCallActionSnapshot", "callId", "recipient", "recipientIndex", "status", "conditionResult", "attemptCount", "maxAttempts", "nextAttemptAt", "providerMessageId", "renderedSubject", "renderedBody", "recipientsSnapshot", "lastError", "lastErrorAt", "errorHistory", "currentJobId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "log_123", "name": "action execution logs", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: post-call-actions:read", "details": { "requiredScope": "post-call-actions:read", "routeId": "actionExecutionLogs.list" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: post-call-actions:read", "Action Execution Logs"], "summary": "List action execution logs", "description": "List action execution logs.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `post-call-actions:read`. Risk class: `standard`. Route ID: `actionExecutionLogs.list`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/action-execution-logs?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/action-execution-logs/{id}": { "get": { "operationId": "actionExecutionLogs.get", "x-api-key-required-scope": "post-call-actions:read", "x-api-key-risk-class": "standard", "x-route-id": "actionExecutionLogs.get", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "postCallActionId": { "type": ["string", "null"] }, "postCallActionSnapshot": { "type": "object", "additionalProperties": true }, "callId": { "type": "string" }, "recipient": { "type": ["string", "null"] }, "recipientIndex": { "type": "number" }, "status": { "type": "string", "enum": [ "pending", "evaluating_llm", "skipped", "queued", "sending", "sent", "retrying", "failed", "dead" ] }, "conditionResult": { "type": ["object", "null"], "properties": { "status": { "type": "string", "enum": ["true", "false"] }, "reason": { "type": "string" }, "llmResults": { "type": "object", "additionalProperties": { "type": "object", "properties": { "result": { "type": "boolean" }, "reason": { "type": "string" } }, "required": ["result", "reason"], "additionalProperties": false } } }, "required": ["status"], "additionalProperties": false }, "attemptCount": { "type": "number" }, "maxAttempts": { "type": "number" }, "nextAttemptAt": { "type": ["string", "null"], "format": "date-time" }, "providerMessageId": { "type": ["string", "null"] }, "renderedSubject": { "type": ["string", "null"] }, "renderedBody": { "type": ["string", "null"] }, "recipientsSnapshot": { "type": "object", "additionalProperties": true }, "lastError": { "type": ["string", "null"] }, "lastErrorAt": { "type": ["string", "null"], "format": "date-time" }, "errorHistory": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "number" }, "at": { "type": "string" }, "error": { "type": "string" } }, "required": ["attempt", "at", "error"], "additionalProperties": false } }, "currentJobId": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "postCallActionId", "postCallActionSnapshot", "callId", "recipient", "recipientIndex", "status", "conditionResult", "attemptCount", "maxAttempts", "nextAttemptAt", "providerMessageId", "renderedSubject", "renderedBody", "recipientsSnapshot", "lastError", "lastErrorAt", "errorHistory", "currentJobId", "createdAt", "updatedAt" ], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "log_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: post-call-actions:read", "details": { "requiredScope": "post-call-actions:read", "routeId": "actionExecutionLogs.get" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: post-call-actions:read", "Action Execution Logs"], "summary": "Get action execution logs", "description": "Get action execution logs.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `post-call-actions:read`. Risk class: `standard`. Route ID: `actionExecutionLogs.get`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/action-execution-logs/kb_123?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/action-execution-logs/{id}/retry": { "post": { "operationId": "actionExecutionLogs.retry", "x-api-key-required-scope": "post-call-actions:execute", "x-api-key-risk-class": "high", "x-route-id": "actionExecutionLogs.retry", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": ["ok"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "id": "log_123", "status": "ok", "updatedAt": "2026-06-01T00:00:00Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: post-call-actions:execute", "details": { "requiredScope": "post-call-actions:execute", "routeId": "actionExecutionLogs.retry" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: post-call-actions:execute", "Action Execution Logs"], "summary": "Retry action execution", "description": "Retry action execution.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `post-call-actions:execute`. Risk class: `high`. Route ID: `actionExecutionLogs.retry`.\n\nExample:\n\n```sh\ncurl -sS -X POST \"https://api.voiceagent.example/api/v1/action-execution-logs/kb_123/retry\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '@request.json'\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } }, "/api/v1/calls/{callId}/execution-logs": { "get": { "operationId": "calls.listExecutionLogs", "x-api-key-required-scope": "calls:read", "x-api-key-risk-class": "standard", "x-route-id": "calls.listExecutionLogs", "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "callId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "postCallActionId": { "type": ["string", "null"] }, "postCallActionSnapshot": { "type": "object", "additionalProperties": true }, "callId": { "type": "string" }, "recipient": { "type": ["string", "null"] }, "recipientIndex": { "type": "number" }, "status": { "type": "string", "enum": [ "pending", "evaluating_llm", "skipped", "queued", "sending", "sent", "retrying", "failed", "dead" ] }, "conditionResult": { "type": ["object", "null"], "properties": { "status": { "type": "string", "enum": ["true", "false"] }, "reason": { "type": "string" }, "llmResults": { "type": "object", "additionalProperties": { "type": "object", "properties": { "result": { "type": "boolean" }, "reason": { "type": "string" } }, "required": ["result", "reason"], "additionalProperties": false } } }, "required": ["status"], "additionalProperties": false }, "attemptCount": { "type": "number" }, "maxAttempts": { "type": "number" }, "nextAttemptAt": { "type": ["string", "null"], "format": "date-time" }, "providerMessageId": { "type": ["string", "null"] }, "renderedSubject": { "type": ["string", "null"] }, "renderedBody": { "type": ["string", "null"] }, "recipientsSnapshot": { "type": "object", "additionalProperties": true }, "lastError": { "type": ["string", "null"] }, "lastErrorAt": { "type": ["string", "null"], "format": "date-time" }, "errorHistory": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "number" }, "at": { "type": "string" }, "error": { "type": "string" } }, "required": ["attempt", "at", "error"], "additionalProperties": false } }, "currentJobId": { "type": ["string", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workspaceId", "postCallActionId", "postCallActionSnapshot", "callId", "recipient", "recipientIndex", "status", "conditionResult", "attemptCount", "maxAttempts", "nextAttemptAt", "providerMessageId", "renderedSubject", "renderedBody", "recipientsSnapshot", "lastError", "lastErrorAt", "errorHistory", "currentJobId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": ["string", "null"] } }, "required": ["nextCursor"], "additionalProperties": false } }, "required": ["items", "pagination"], "additionalProperties": false }, "examples": { "success": { "summary": "Successful response", "value": { "items": [ { "id": "log_123", "name": "execution logs", "createdAt": "2026-06-01T00:00:00Z", "updatedAt": "2026-06-01T00:00:00Z" } ], "pagination": { "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA2LTAxVDAwOjAwOjAwWiJ9" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "validationError": { "summary": "Validation error", "value": { "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": { "fieldErrors": { "limit": ["Number must be less than or equal to 200"] } }, "requestId": "req_123" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "unauthorized": { "summary": "Authentication error", "value": { "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key", "requestId": "req_123" } } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] }, "examples": { "scopeInsufficient": { "summary": "Required scope missing", "value": { "error": { "code": "SCOPE_INSUFFICIENT", "message": "Required scope: calls:read", "details": { "requiredScope": "calls:read", "routeId": "calls.listExecutionLogs" } } } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "requestId": { "type": "string" } }, "required": ["code", "message"] } }, "required": ["error"] } } } } }, "tags": ["Scope: calls:read", "Action Execution Logs"], "summary": "Get execution logs", "description": "Get execution logs.\n\nUse this Tier A public endpoint from partner backends after authenticating with a workspace API key. The operation is scoped to the authenticated workspace and returns the documented VoiceAgent response envelope for list and error cases.\n\nRequired API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.listExecutionLogs`.\n\nExample:\n\n```sh\ncurl -sS -X GET \"https://api.voiceagent.example/api/v1/calls/call_123/execution-logs?limit=50\" \\\n -H \"Authorization: Bearer ${VOICEAGENT_API_KEY}\"\n```\n\nNew integrations must use the versioned `/api/v1/` path shown here. For compatibility windows, deprecation headers, and sunset rules, see [Versioning and deprecation](https://api-docs.voiceagent.example/versioning-and-deprecation.html)." } } }, "webhooks": {}, "servers": [ { "url": "https://api.voiceagent.example/api/v1", "description": "Production placeholder. Public v1 base URL for partner integrations." }, { "url": "https://api-dev.voiceagent.example/api/v1", "description": "Development placeholder. Use for sandbox and pre-production validation." } ], "tags": [ { "name": "Scope: agents:read", "description": "Operations requiring the `agents:read` API key scope." }, { "name": "Scope: agents:write", "description": "Operations requiring the `agents:write` API key scope." }, { "name": "Scope: agents:admin", "description": "Operations requiring the `agents:admin` API key scope." }, { "name": "Scope: agents:execute", "description": "Operations requiring the `agents:execute` API key scope." }, { "name": "Scope: knowledge-bases:read", "description": "Operations requiring the `knowledge-bases:read` API key scope." }, { "name": "Scope: knowledge-bases:write", "description": "Operations requiring the `knowledge-bases:write` API key scope." }, { "name": "Scope: entity-indexes:read", "description": "Operations requiring the `entity-indexes:read` API key scope." }, { "name": "Scope: entity-indexes:write", "description": "Operations requiring the `entity-indexes:write` API key scope." }, { "name": "Scope: phone-numbers:read", "description": "Operations requiring the `phone-numbers:read` API key scope." }, { "name": "Scope: phone-numbers:write", "description": "Operations requiring the `phone-numbers:write` API key scope." }, { "name": "Scope: calls:read", "description": "Operations requiring the `calls:read` API key scope." }, { "name": "Scope: calls:execute", "description": "Operations requiring the `calls:execute` API key scope." }, { "name": "Scope: analytics:read", "description": "Operations requiring the `analytics:read` API key scope." }, { "name": "Scope: post-call-actions:read", "description": "Operations requiring the `post-call-actions:read` API key scope." }, { "name": "Scope: post-call-actions:write", "description": "Operations requiring the `post-call-actions:write` API key scope." }, { "name": "Scope: post-call-actions:execute", "description": "Operations requiring the `post-call-actions:execute` API key scope." }, { "name": "Scope: api-keys:read", "description": "Operations requiring the `api-keys:read` API key scope." }, { "name": "Scope: api-keys:write", "description": "Operations requiring the `api-keys:write` API key scope." }, { "name": "Scope: api-keys:admin", "description": "Operations requiring the `api-keys:admin` API key scope." }, { "name": "Scope: workspace:read", "description": "Operations requiring the `workspace:read` API key scope." }, { "name": "Scope: workspace:write", "description": "Operations requiring the `workspace:write` API key scope." }, { "name": "Scope: workspace:admin", "description": "Operations requiring the `workspace:admin` API key scope." }, { "name": "Scope: webhooks:read", "description": "Operations requiring the `webhooks:read` API key scope." }, { "name": "Scope: webhooks:write", "description": "Operations requiring the `webhooks:write` API key scope." }, { "name": "Scope: webhooks:execute", "description": "Operations requiring the `webhooks:execute` API key scope." }, { "name": "Scope: test-scenarios:read", "description": "Operations requiring the `test-scenarios:read` API key scope." }, { "name": "Scope: test-scenarios:write", "description": "Operations requiring the `test-scenarios:write` API key scope." }, { "name": "Scope: test-scenarios:execute", "description": "Operations requiring the `test-scenarios:execute` API key scope." }, { "name": "Agents", "description": "Create, publish, tune, and inspect voice agents that own call behavior and runtime configuration." }, { "name": "Agent Knowledge", "description": "Attach knowledge bases to agents, skills, and nodes so runtime answers can use workspace content." }, { "name": "Agent Webhooks", "description": "Manage webhooks scoped to a single agent for event delivery and endpoint smoke tests." }, { "name": "Skills", "description": "Manage reusable agent skills, skill prompts, node graphs, and skill-level knowledge retrieval." }, { "name": "Test Scenarios", "description": "Create reusable voice-agent test scenarios, run them, inspect iterations, and cancel active runs." }, { "name": "Calls", "description": "Create phone or web calls, inspect queue state, fetch call details, recordings, transcripts, and turn metrics." }, { "name": "Phone Numbers", "description": "Provision, import, assign, update, and release workspace phone numbers for inbound and outbound calls." }, { "name": "API Keys", "description": "Issue and revoke workspace API keys. Raw key material is returned only during creation." }, { "name": "Webhooks", "description": "Manage workspace webhook endpoints, custom headers, subscriptions, and delivery tests." }, { "name": "Workspace", "description": "Inspect and update workspace metadata, caller role, members, and knowledge-base defaults." }, { "name": "Analytics", "description": "Read workspace analytics snapshots for operational reporting and partner dashboards." }, { "name": "Knowledge Bases", "description": "Manage retrieval knowledge bases, Q&A documents, document versions, sync state, usage, and analytics." }, { "name": "Entity Indexes", "description": "Manage structured entity indexes and indexed documents used for deterministic entity lookup." }, { "name": "Post-Call Actions", "description": "Configure and test post-call automations such as email and SMS workflows driven by call results." }, { "name": "Action Execution Logs", "description": "Inspect and retry post-call action execution logs for audit, troubleshooting, and recovery workflows." } ], "security": [ { "ApiKeyAuth": [] }, { "XApiKeyAuth": [] } ] }