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: &a1 - 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: &a2 - 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: &a3 - 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: &a4 - 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: &a5 - 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. Use 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. Required API key scope: `agents:read`. Risk class: `standard`. Route ID: `agents.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a1 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: *a2 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: *a3 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: *a4 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: *a5 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. Use 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. Required API key scope: `agents:write`. Risk class: `standard`. Route ID: `agents.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/agents" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: *a1 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: *a2 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: *a3 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: *a4 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: *a5 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. Use 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. Required API key scope: `agents:read`. Risk class: `standard`. Route ID: `agents.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/kb_123?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a1 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: *a2 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: *a3 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: *a4 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: *a5 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. Use 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. Required API key scope: `agents:write`. Risk class: `standard`. Route ID: `agents.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/agents/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `agents:write`. Risk class: `standard`. Route ID: `agents.delete`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/agents/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a1 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: *a2 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: *a3 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: *a4 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: *a5 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. Use 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. Required API key scope: `agents:admin`. Risk class: `standard`. Route ID: `agents.publish`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/agents/kb_123/publish" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: &a19 - 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. Use 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. Required API key scope: `agents:read`. Risk class: `standard`. Route ID: `agents.listKnowledgeBases`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/kb_123/knowledge-bases?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `agents:write`. Risk class: `standard`. Route ID: `agents.replaceKnowledgeBases`. Example: ```sh curl -sS -X PUT "https://api.voiceagent.example/api/v1/agents/kb_123/knowledge-bases" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: &a6 - ready - processing - error source: type: string enum: &a7 - 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: *a6 source: type: string enum: *a7 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: *a6 source: type: string enum: *a7 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. Use 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. Required API key scope: `agents:read`. Risk class: `standard`. Route ID: `agentKnowledgeOverview.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/agt_123/kb-overview?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: &a8 - 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. Use 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. Required API key scope: `webhooks:read`. Risk class: `standard`. Route ID: `agentWebhooks.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/agt_123/webhooks?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a8 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: *a8 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. Use 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. Required API key scope: `webhooks:write`. Risk class: `high`. Route ID: `agentWebhooks.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/agents/agt_123/webhooks" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: *a8 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: *a8 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. Use 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. Required API key scope: `webhooks:write`. Risk class: `high`. Route ID: `agentWebhooks.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/agents/agt_123/webhooks/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `webhooks:write`. Risk class: `high`. Route ID: `agentWebhooks.delete`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/agents/agt_123/webhooks/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `webhooks:execute`. Risk class: `standard`. Route ID: `agentWebhooks.test`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/agents/agt_123/webhooks/kb_123/test" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `agents:write`. Risk class: `standard`. Route ID: `skills.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/agents/agt_123/skills" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `agents:read`. Risk class: `standard`. Route ID: `skills.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/agt_123/skills?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `agents:read`. Risk class: `standard`. Route ID: `skills.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `agents:write`. Risk class: `standard`. Route ID: `skills.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `agents:write`. Risk class: `standard`. Route ID: `skills.delete`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: &a9 - 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: *a9 required: - id - name - source additionalProperties: false agent: type: array items: type: object properties: id: type: string name: type: string source: type: string enum: *a9 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. Use 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. Required API key scope: `agents:read`. Risk class: `standard`. Route ID: `skillKnowledgeBases.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123/knowledge-bases?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `agents:write`. Risk class: `standard`. Route ID: `skillKnowledgeBases.replace`. Example: ```sh curl -sS -X PUT "https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123/knowledge-bases" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: *a9 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. Use 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. Required API key scope: `agents:read`. Risk class: `standard`. Route ID: `skillKnowledgeBases.listEffectiveForNode`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123/nodes/node_123/effective-kbs?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `agents:read`. Risk class: `standard`. Route ID: `skillKnowledgeConfig.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123/kb-config?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `agents:write`. Risk class: `standard`. Route ID: `skillKnowledgeConfig.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/agents/agt_123/skills/skill_123/kb-config" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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] name = "greeting_smoke_test" 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. Use 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. Required API key scope: `agents:execute`. Risk class: `standard`. Route ID: `agents.uploadSimulationDump`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/agents/kb_123/simulations/sess_123/dump" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: &a10 - 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. Use 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. Required API key scope: `test-scenarios:write`. Risk class: `standard`. Route ID: `testScenarios.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/agents/agt_123/test-scenarios" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: *a10 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. Use 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. Required API key scope: `test-scenarios:read`. Risk class: `standard`. Route ID: `testScenarios.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/agt_123/test-scenarios?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a10 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. Use 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. Required API key scope: `test-scenarios:read`. Risk class: `standard`. Route ID: `testScenarios.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/agt_123/test-scenarios/kb_123?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a10 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. Use 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. Required API key scope: `test-scenarios:write`. Risk class: `standard`. Route ID: `testScenarios.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/agents/agt_123/test-scenarios/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `test-scenarios:write`. Risk class: `standard`. Route ID: `testScenarios.delete`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/agents/agt_123/test-scenarios/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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 mode: component 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. Use 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. Required API key scope: `test-scenarios:write`. Risk class: `standard`. Route ID: `testScenarios.import`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/agents/agt_123/test-scenarios/import" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: &a11 - 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. Use 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. Required API key scope: `test-scenarios:execute`. Risk class: `standard`. Route ID: `testRuns.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/agents/agt_123/test-runs" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: *a11 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. Use 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. Required API key scope: `test-scenarios:read`. Risk class: `standard`. Route ID: `testRuns.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/agt_123/test-runs?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a11 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. Use 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. Required API key scope: `test-scenarios:read`. Risk class: `standard`. Route ID: `testRuns.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/agt_123/test-runs/kb_123?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `test-scenarios:read`. Risk class: `standard`. Route ID: `testRuns.listIterations`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/agents/agt_123/test-runs/kb_123/iterations?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `test-scenarios:execute`. Risk class: `standard`. Route ID: `testRuns.cancel`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/agents/agt_123/test-runs/kb_123/cancel" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: &a12 - queued - registered - not_connected - ongoing - ended - error direction: type: string enum: &a13 - inbound - outbound callType: type: string enum: &a14 - 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: &a15 - 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: &a16 - 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. Use 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. Required API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/calls?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a12 direction: type: string enum: *a13 callType: type: string enum: *a14 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: *a15 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: *a16 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. Use 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. Required API key scope: `calls:execute`. Risk class: `high`. Route ID: `calls.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/calls" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.queueStatus`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/calls/queue-status" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a12 direction: type: string enum: *a13 callType: type: string enum: *a14 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: *a15 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: *a16 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. Use 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. Required API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/calls/kb_123?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a12 direction: type: string enum: *a13 callType: type: string enum: *a14 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: *a15 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: *a16 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. Use 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. Required API key scope: `calls:execute`. Risk class: `high`. Route ID: `calls.createPhone`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/calls/phone" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: *a12 direction: type: string enum: *a13 callType: type: string enum: *a14 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: *a15 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: *a16 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. Use 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. Required API key scope: `calls:execute`. Risk class: `high`. Route ID: `calls.createWeb`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/calls/web" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.getRecording`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/calls/kb_123/recording?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a15 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. Use 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. Required API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.getTranscript`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/calls/kb_123/transcript?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.getTurnMetrics`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/calls/kb_123/turn-metrics?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `phone-numbers:read`. Risk class: `standard`. Route ID: `phoneNumbers.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/phone-numbers?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `phone-numbers:write`. Risk class: `high`. Route ID: `phoneNumbers.buy`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/phone-numbers" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `phone-numbers:write`. Risk class: `high`. Route ID: `phoneNumbers.import`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/phone-numbers/import" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `phone-numbers:read`. Risk class: `standard`. Route ID: `phoneNumbers.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/phone-numbers/kb_123?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `phone-numbers:write`. Risk class: `high`. Route ID: `phoneNumbers.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/phone-numbers/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `phone-numbers:write`. Risk class: `high`. Route ID: `phoneNumbers.release`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/phone-numbers/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `api-keys:read`. Risk class: `standard`. Route ID: `apiKeys.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/api-keys?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `api-keys:write`. Risk class: `high`. Route ID: `apiKeys.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/api-keys" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `api-keys:write`. Risk class: `high`. Route ID: `apiKeys.rotate`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/api-keys/kb_123/rotate" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `api-keys:admin`. Risk class: `high`. Route ID: `apiKeys.revoke`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/api-keys/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a8 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. Use 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. Required API key scope: `webhooks:read`. Risk class: `standard`. Route ID: `webhooks.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/webhooks?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a8 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: *a8 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. Use 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. Required API key scope: `webhooks:write`. Risk class: `high`. Route ID: `webhooks.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/webhooks" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: *a8 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: *a8 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. Use 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. Required API key scope: `webhooks:write`. Risk class: `high`. Route ID: `webhooks.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/webhooks/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `webhooks:write`. Risk class: `high`. Route ID: `webhooks.delete`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/webhooks/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `webhooks:execute`. Risk class: `standard`. Route ID: `webhooks.test`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/webhooks/kb_123/test" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: &a17 - 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. Use 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. Required API key scope: `workspace:read`. Risk class: `standard`. Route ID: `workspace.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/workspace?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a17 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. Use 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. Required API key scope: `workspace:write`. Risk class: `standard`. Route ID: `workspace.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/workspace" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `workspace:admin`. Risk class: `high`. Route ID: `workspace.delete`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/workspace" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `workspace:read`. Risk class: `standard`. Route ID: `workspace.getMyRole`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/workspace/me/role?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: &a18 - 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. Use 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. Required API key scope: `workspace:read`. Risk class: `standard`. Route ID: `workspaceMembers.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/workspace/members?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a18 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. Use 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. Required API key scope: `workspace:admin`. Risk class: `high`. Route ID: `workspaceMembers.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/workspace/members/mem_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `workspace:admin`. Risk class: `high`. Route ID: `workspaceMembers.remove`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/workspace/members/mem_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `analytics:read`. Risk class: `standard`. Route ID: `analytics.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/analytics?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a19 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. Use 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. Required API key scope: `workspace:read`. Risk class: `standard`. Route ID: `workspaceDefaults.listKnowledgeBases`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/knowledge-bases/workspace-defaults?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `workspace:admin`. Risk class: `high`. Route ID: `workspaceDefaults.replaceKnowledgeBases`. Example: ```sh curl -sS -X PUT "https://api.voiceagent.example/api/v1/knowledge-bases/workspace-defaults" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBaseUsage.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/knowledge-bases/{kbId}/usage?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a19 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. Use 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. Required API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBases.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/knowledge-bases?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a19 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. Use 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. Required API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBases.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/knowledge-bases" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: *a19 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. Use 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. Required API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBases.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/knowledge-bases/kb_123?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a19 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. Use 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. Required API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBases.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/knowledge-bases/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBases.delete`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/knowledge-bases/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: &a20 - 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. Use 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. Required API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBaseDocuments.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a20 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. Use 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. Required API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBaseDocuments.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: *a20 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. Use 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. Required API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBaseDocuments.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents/doc_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBaseDocuments.delete`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents/doc_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBaseDocuments.deleteAll`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents/delete-all" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBaseDocumentVersions.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents/doc_123/versions?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a20 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. Use 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. Required API key scope: `knowledge-bases:write`. Risk class: `standard`. Route ID: `knowledgeBaseDocuments.rollback`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/documents/doc_123/rollback" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBases.getSyncStatus`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/sync-status?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `knowledge-bases:read`. Risk class: `standard`. Route ID: `knowledgeBaseAnalytics.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/knowledge-bases/kb_123/analytics?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: &a21 - ready - processing - error schemaFields: type: array items: type: object properties: name: type: string type: type: string enum: &a22 - 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. Use 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. Required API key scope: `entity-indexes:read`. Risk class: `standard`. Route ID: `entityIndexes.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/entity-indexes?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: &a23 - 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: *a21 schemaFields: type: array items: type: object properties: name: type: string type: type: string enum: *a22 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. Use 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. Required API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityIndexes.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/entity-indexes" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: *a21 schemaFields: type: array items: type: object properties: name: type: string type: type: string enum: *a22 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. Use 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. Required API key scope: `entity-indexes:read`. Risk class: `standard`. Route ID: `entityIndexes.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/entity-indexes/kb_123?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a23 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: *a21 schemaFields: type: array items: type: object properties: name: type: string type: type: string enum: *a22 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. Use 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. Required API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityIndexes.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/entity-indexes/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityIndexes.delete`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/entity-indexes/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `entity-indexes:read`. Risk class: `standard`. Route ID: `entityIndexes.getSyncStatus`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/entity-indexes/kb_123/sync-status?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: &a24 - 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. Use 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. Required API key scope: `entity-indexes:read`. Risk class: `standard`. Route ID: `entityDocuments.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a24 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. Use 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. Required API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityDocuments.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityDocuments.deleteAll`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents/delete-all" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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 cust_123,Example Customer 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. Use 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. Required API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityDocuments.import`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents/import" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: *a24 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. Use 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. Required API key scope: `entity-indexes:read`. Risk class: `standard`. Route ID: `entityDocuments.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents/doc_123?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a24 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. Use 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. Required API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityDocuments.update`. Example: ```sh curl -sS -X PATCH "https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents/doc_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `entity-indexes:write`. Risk class: `standard`. Route ID: `entityDocuments.delete`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/entity-indexes/kb_123/documents/doc_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: &a25 combinator: type: string enum: - AND - OR children: type: array items: type: object additionalProperties: true required: &a26 - combinator - children actionType: type: string enum: &a27 - 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: &a28 - 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: &a29 - 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. Use 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. Required API key scope: `post-call-actions:read`. Risk class: `standard`. Route ID: `postCallActions.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/post-call-actions?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: &a30 combinator: type: string enum: - AND - OR children: type: array items: type: object additionalProperties: true maxItems: 20 required: &a31 - combinator - children actionType: type: string enum: &a32 - 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: &a33 - 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: &a34 - 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: *a25 required: *a26 actionType: type: string enum: *a27 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: *a28 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: *a29 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. Use 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. Required API key scope: `post-call-actions:write`. Risk class: `standard`. Route ID: `postCallActions.create`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/post-call-actions" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `post-call-actions:read`. Risk class: `standard`. Route ID: `postCallActions.getSchemaVariables`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/post-call-actions/schema/variables?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a25 required: *a26 actionType: type: string enum: *a27 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: *a28 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: *a29 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. Use 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. Required API key scope: `post-call-actions:read`. Risk class: `standard`. Route ID: `postCallActions.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/post-call-actions/kb_123?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a30 required: *a31 actionType: type: string enum: *a32 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: *a33 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: *a34 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: *a25 required: *a26 actionType: type: string enum: *a27 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: *a28 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: *a29 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. Use 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. Required API key scope: `post-call-actions:write`. Risk class: `standard`. Route ID: `postCallActions.update`. Example: ```sh curl -sS -X PUT "https://api.voiceagent.example/api/v1/post-call-actions/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `post-call-actions:write`. Risk class: `standard`. Route ID: `postCallActions.delete`. Example: ```sh curl -sS -X DELETE "https://api.voiceagent.example/api/v1/post-call-actions/kb_123" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a25 required: *a26 actionType: type: string enum: *a27 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: *a28 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: *a29 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. Use 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. Required API key scope: `post-call-actions:write`. Risk class: `standard`. Route ID: `postCallActions.toggle`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/post-call-actions/kb_123/toggle" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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. Use 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. Required API key scope: `post-call-actions:execute`. Risk class: `high`. Route ID: `postCallActions.test`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/post-call-actions/kb_123/test" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: &a35 - pending - evaluating_llm - skipped - queued - sending - sent - retrying - failed - dead conditionResult: type: - object - "null" properties: status: type: string enum: &a36 - "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. Use 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. Required API key scope: `post-call-actions:read`. Risk class: `standard`. Route ID: `postCallActions.listExecutionLogs`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/post-call-actions/kb_123/execution-logs?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a35 conditionResult: type: - object - "null" properties: status: type: string enum: *a36 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. Use 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. Required API key scope: `post-call-actions:read`. Risk class: `standard`. Route ID: `actionExecutionLogs.list`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/action-execution-logs?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: *a35 conditionResult: type: - object - "null" properties: status: type: string enum: *a36 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. Use 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. Required API key scope: `post-call-actions:read`. Risk class: `standard`. Route ID: `actionExecutionLogs.get`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/action-execution-logs/kb_123?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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. Use 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. Required API key scope: `post-call-actions:execute`. Risk class: `high`. Route ID: `actionExecutionLogs.retry`. Example: ```sh curl -sS -X POST "https://api.voiceagent.example/api/v1/action-execution-logs/kb_123/retry" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" \ -H "Content-Type: application/json" \ -d '@request.json' ``` New 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: *a35 conditionResult: type: - object - "null" properties: status: type: string enum: *a36 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. Use 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. Required API key scope: `calls:read`. Risk class: `standard`. Route ID: `calls.listExecutionLogs`. Example: ```sh curl -sS -X GET "https://api.voiceagent.example/api/v1/calls/call_123/execution-logs?limit=50" \ -H "Authorization: Bearer ${VOICEAGENT_API_KEY}" ``` New 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: []