openapi: 3.0.1 info: title: SigmaMind APIs description: OpenAPI documentation SigmaMind Agent Builder APIs version: "1.0" servers: - url: https://api.sigmamind.ai description: SigmaMind AI Agent Builder APIs security: - apiKeyAuth: [] tags: - name: Chats description: "Endpoints for creating and managing text-based chat sessions with\ \ an agent. A session is started by specifying an agent and an opening message.\ \ Returns a chatId used in all subsequent get, update, completion, and end-session\ \ calls." - name: Calls description: "Endpoints for creating and managing outbound phone calls. A call is\ \ initiated by specifying an agent, caller number, and destination number — dynamic\ \ variables can be included to personalise the agent's behaviour. Returns a callId\ \ used in all subsequent get and delete operations." - name: Phone Numbers description: "Endpoints for managing phone numbers used in outbound and inbound calls. Supports purchasing a new number through SigmaMind or importing an existing number via SIP trunking (BYO). Each number can be assigned separate inbound and outbound agents." - name: Campaigns description: "Endpoints for creating and managing outbound call campaigns. A campaign\ \ dials a CSV-uploaded contact list using a selected agent and caller number,\ \ with support for immediate or scheduled launch. Returns a campaignId used in\ \ all subsequent get, update, and delete operations." - name: Agents description: "Endpoints for creating and managing single prompt agents. An agent\ \ is configured with a system prompt, voice settings, and optional tools. Returns\ \ an agentId used in all subsequent update, call, and simulation operations." - name: Integrations description: "Endpoints for creating and managing third-party integrations (e.g.\ \ Shopify, Cal.com). An integration links your account to an external service\ \ and acts as the parent resource for auth credentials and API tools. Returns\ \ an integrationId used in all subsequent auth and tool operations." - name: Integration Auth description: "Endpoints for managing authentication credentials for a third-party\ \ integration. Supports API Key, Basic, and Bearer token credential types — scoped\ \ to an integration and injected automatically by tools when executing. Returns\ \ an authId used in all subsequent get, update, and delete operations." - name: Integration Tools description: "Endpoints for creating and managing API tools backed by a third-party\ \ integration. Each tool defines an HTTP endpoint, method, and parameter schema\ \ — scoped to an integration and using its stored auth credentials when executing.\ \ Returns a toolId used in all subsequent get, update, delete, and execute operations." - name: Webhooks description: "Endpoints for registering and managing webhooks. A webhook delivers real-time event notifications via HTTP POST when selected events occur on a specific agent — each webhook is scoped to one agent and one or more event types. Payloads are signed with an HMAC secret — verify the signature on your server to confirm authenticity." - name: Test Cases description: "Endpoints for creating and managing simulation test cases for an agent.\ \ A test case defines a conversation scenario — including user persona, goals,\ \ and expected behaviour — used to generate a synthetic conversation with the\ \ agent. Returns a testCaseId used in all subsequent get, update, delete, and\ \ batch-run operations." - name: Batch Runs description: "Endpoints for creating and managing batch runs of simulation test cases. A batch run executes multiple test cases in parallel against a selected agent and aggregates the results for review. Returns a batchId used in all subsequent get and list test-run operations." - name: Test Runs description: "Endpoints for retrieving test run results within a batch. Each test\ \ run represents a single test case execution within a batch run, identified by\ \ a jobId. Use batchId and agentId to scope results to the correct batch." - name: API Keys description: "Endpoints for creating and managing API keys used to authenticate\ \ public API requests. Each key must be included in the X-API-Key request header.\ \ Returns a keyId used in all subsequent get, revoke, and delete operations." - name: QA Rules description: "Endpoints for creating and managing quality assurance rules applied to agent conversations. A QA rule defines evaluation criteria used to automatically assess conversation quality. Returns a qaRuleId used in all subsequent get, update, and delete operations." - name: QA Issues description: "Endpoints for retrieving and managing quality assurance issues flagged across agent conversations. A QA issue is created with status 'Fail' when a conversation violates one or more QA rules — capturing the offending rule reference. It is created with status 'Success' when the conversation passes the evaluation criteria of QA rule(s). Returns a qaIssueId used in all subsequent get operations." - name: Mock Tool Data description: Endpoints for creating and managing reusable mocked tool responses. Mocks are tenant-scoped library objects that can be bound to test cases by tool alias. Returns a mockToolDataId used when attaching mocks to test cases via mockToolData. paths: # Calls APIs /v1/calls: get: tags: - Calls summary: List Phone Calls description: "Returns a paginated list of call records for the account, sorted\ \ by most recently created first. Use the status parameter to filter by call\ \ state. Use page and size to navigate through results." operationId: listPhoneCall parameters: - name: status in: query description: "Filter calls by their current state. Accepted values: 'scheduled',\ \ 'in_progress', 'ended', 'not_connected', 'error'. Omit to return calls\ \ in all states." required: false schema: type: string example: ended - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of calls to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseCallResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/calls status: 400 timestamp: 2026-05-05T10:06:43.846335 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/calls status: 401 timestamp: 2026-05-05T10:06:43.846359 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/calls status: 403 timestamp: 2026-05-05T10:06:43.846366 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/calls status: 404 timestamp: 2026-05-05T10:06:43.846372 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/calls status: 500 timestamp: 2026-05-05T10:06:43.846385 post: tags: - Calls summary: Create Phone Call description: "Initiates an outbound call with the specified agent, caller, and\ \ destination numbers. Supports dynamic variables for personalization. Returns\ \ the created call record, including the callId for future retrieval or cancellation." operationId: createPhoneCall requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCallRequest' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/CallResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/calls status: 400 timestamp: 2026-05-05T10:06:43.691550 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/calls status: 401 timestamp: 2026-05-05T10:06:43.691580 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/calls status: 403 timestamp: 2026-05-05T10:06:43.691587 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/calls status: 404 timestamp: 2026-05-05T10:06:43.691594 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/calls status: 500 timestamp: 2026-05-05T10:06:43.691629 /v1/calls/{callId}: get: tags: - Calls summary: Get Phone Call description: "Retrieves the full details of a single call record by callId.\ \ Returns call status, direction, assigned agent, phone numbers, duration,\ \ and transcript metadata." operationId: getPhoneCallByCallId parameters: - name: callId in: path description: "A unique identifier for any call, whether inbound, outbound,\ \ or web-based." required: true schema: type: string example: AuUKK371Spr5nHJS responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/CallResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/calls status: 400 timestamp: 2026-05-05T10:06:43.865269 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/calls status: 401 timestamp: 2026-05-05T10:06:43.865295 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/calls status: 403 timestamp: 2026-05-05T10:06:43.865303 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/calls status: 404 timestamp: 2026-05-05T10:06:43.865308 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/calls status: 500 timestamp: 2026-05-05T10:06:43.865317 delete: tags: - Calls summary: Delete Phone Call description: Permanently deletes a call record by callId. Cannot be undone. Returns 204 No Content on success. operationId: deletePhoneCallByCallId parameters: - name: callId in: path description: "A unique identifier for any call, whether inbound, outbound,\ \ or web-based." required: true schema: type: string example: AuUKK371Spr5nHJS responses: "200": description: OK "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/calls status: 400 timestamp: 2026-05-05T10:06:43.893780 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/calls status: 401 timestamp: 2026-05-05T10:06:43.893808 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/calls status: 403 timestamp: 2026-05-05T10:06:43.893818 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/calls status: 404 timestamp: 2026-05-05T10:06:43.893827 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/calls status: 500 timestamp: 2026-05-05T10:06:43.893839 # Chat APIs /v1/chats: get: tags: - Chats summary: List Chats description: "Returns a paginated list of chat sessions for the account, sorted\ \ by most recently created first. Use the status parameter to filter by session\ \ state. Use page and size to navigate through results." operationId: listChat parameters: - name: status in: query description: "Filter chats by their current session state. Accepted values:\ \ 'in_progress', 'ended'. Omit to return chats in all states." required: false schema: type: string example: in_progress - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of chats to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseChatResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/chats status: 400 timestamp: 2026-05-05T10:06:43.803880 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/chats status: 401 timestamp: 2026-05-05T10:06:43.803914 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/chats status: 403 timestamp: 2026-05-05T10:06:43.803929 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/chats status: 404 timestamp: 2026-05-05T10:06:43.803937 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/chats status: 500 timestamp: 2026-05-05T10:06:43.803954 post: tags: - Chats summary: Create Chat description: "Creates a new chat session with the specified agent and sends\ \ the initial message. Returns the agent’s reply along with the chatId for\ \ subsequent completion, update, and end-session calls." operationId: createChat requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateChatRequest' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/chats status: 400 timestamp: 2026-05-05T10:06:43.615208 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/chats status: 401 timestamp: 2026-05-05T10:06:43.615376 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/chats status: 403 timestamp: 2026-05-05T10:06:43.615403 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/chats status: 404 timestamp: 2026-05-05T10:06:43.615414 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/chats status: 500 timestamp: 2026-05-05T10:06:43.615435 /v1/chats/response: post: tags: - Chats summary: Chat Completion description: Submits a new customer message to an in_progress chat session and returns the agent's reply. The session must be active — calls against an ended session will be rejected. Returns the agent's response and updated session state. operationId: createChatCompletion requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateChatCompletionRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/chats status: 400 timestamp: 2026-05-05T10:06:43.632363 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/chats status: 401 timestamp: 2026-05-05T10:06:43.632399 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/chats status: 403 timestamp: 2026-05-05T10:06:43.632413 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/chats status: 404 timestamp: 2026-05-05T10:06:43.632423 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/chats status: 500 timestamp: 2026-05-05T10:06:43.632444 /v1/chats/{chatId}: get: tags: - Chats summary: Get Chat description: "Retrieves the full details of a single chat session by chatId.\ \ Returns the session status, assigned agent, message history, and dynamic\ \ variables." operationId: getChatByChatId parameters: - name: chatId in: path description: Unique identifier of the chat session to retrieve. required: true schema: type: string example: chat_AuUKK371Spr5nHJS responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/ChatResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/chats status: 400 timestamp: 2026-05-05T10:06:43.816624 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/chats status: 401 timestamp: 2026-05-05T10:06:43.816656 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/chats status: 403 timestamp: 2026-05-05T10:06:43.816666 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/chats status: 404 timestamp: 2026-05-05T10:06:43.816675 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/chats status: 500 timestamp: 2026-05-05T10:06:43.816689 patch: tags: - Chats summary: Update Chat description: Partially updates an in_progress chat session by chatId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated session record. operationId: updateChatSession parameters: - name: chatId in: path description: Unique identifier of the chat session to update. required: true schema: type: string example: chat_AuUKK371Spr5nHJS requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateChatRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/ChatResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/chats status: 400 timestamp: 2026-05-05T10:06:43.724517 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/chats status: 401 timestamp: 2026-05-05T10:06:43.724542 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/chats status: 403 timestamp: 2026-05-05T10:06:43.724549 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/chats status: 404 timestamp: 2026-05-05T10:06:43.724555 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/chats status: 500 timestamp: 2026-05-05T10:06:43.724567 /v1/chats/{chatId}/end-session: patch: tags: - Chats summary: End Chat description: "Ends an in_progress chat session by chatId, marking it as completed.\ \ No further messages can be submitted after a session is ended. Returns the\ \ final session record." operationId: endChatSession parameters: - name: chatId in: path description: Unique identifier of the chat session to end. required: true schema: type: string example: chat_AuUKK371Spr5nHJS responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/ChatResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/chats status: 400 timestamp: 2026-05-05T10:06:43.735144 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/chats status: 401 timestamp: 2026-05-05T10:06:43.735169 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/chats status: 403 timestamp: 2026-05-05T10:06:43.735176 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/chats status: 404 timestamp: 2026-05-05T10:06:43.735183 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/chats status: 500 timestamp: 2026-05-05T10:06:43.735195 # Phone Number APIs /v1/phone-numbers: get: tags: - Phone Numbers summary: List Phone Numbers description: "Returns a paginated list of all phone numbers registered on the\ \ account, sorted by most recently added first. Includes both SigmaMind-provisioned\ \ numbers and BYO numbers imported via SIP trunking. Use page and size to\ \ navigate through results." operationId: listPhoneNumber parameters: - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of phone numbers to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponsePhoneNumberResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/phone-numbers status: 400 timestamp: 2026-05-05T10:06:46.064354 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/phone-numbers status: 401 timestamp: 2026-05-05T10:06:46.064379 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/phone-numbers status: 403 timestamp: 2026-05-05T10:06:46.064386 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/phone-numbers status: 404 timestamp: 2026-05-05T10:06:46.064392 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/phone-numbers status: 500 timestamp: 2026-05-05T10:06:46.064403 post: tags: - Phone Numbers summary: Create Phone Number description: "Purchases and provisions a new phone number for your account.\ \ Provide a specific phoneNumber in +E.164 format, or a countryCode (optionally\ \ areaCode) to auto-select one. Returns the provisioned number, including\ \ its sipPhoneNumber for subsequent get, update, and delete calls." operationId: createPhoneNumber requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePhoneNumberRequest_Telephony' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/PhoneNumberResponse_Telephony' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/phone-numbers status: 400 timestamp: 2026-05-05T10:06:45.708274 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/phone-numbers status: 401 timestamp: 2026-05-05T10:06:45.708310 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/phone-numbers status: 403 timestamp: 2026-05-05T10:06:45.708322 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/phone-numbers status: 404 timestamp: 2026-05-05T10:06:45.708333 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/phone-numbers status: 500 timestamp: 2026-05-05T10:06:45.708352 /v1/phone-numbers/import: post: tags: - Phone Numbers summary: Import Phone Number description: "Imports an existing phone number via SIP trunking (BYO). Provide\ \ the number in +E.164 format along with SIP credentials (trunkUsername, trunkPassword,\ \ terminationSipURI). Returns the imported number, including its sipPhoneNumber." operationId: importPhoneNumber requestBody: content: application/json: schema: $ref: '#/components/schemas/ImportPhoneNumberRequest_Byo' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/PhoneNumberResponse_Byo' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/phone-numbers status: 400 timestamp: 2026-05-05T10:06:45.720077 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/phone-numbers status: 401 timestamp: 2026-05-05T10:06:45.720116 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/phone-numbers status: 403 timestamp: 2026-05-05T10:06:45.720129 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/phone-numbers status: 404 timestamp: 2026-05-05T10:06:45.720138 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/phone-numbers status: 500 timestamp: 2026-05-05T10:06:45.720158 /v1/phone-numbers/{phoneNumber}: get: tags: - Phone Numbers summary: Get Phone Number description: "Retrieves the full configuration of a single phone number by its\ \ +E.164 value. Returns assigned agents, active status, provider, and SIP\ \ configuration for BYO numbers." operationId: getPhoneNumber parameters: - name: phoneNumber in: path description: "Phone number to retrieve, in +E.164 format. Obtained from the\ \ sipPhoneNumber field in the Create, Import, or List Phone Numbers response." required: true schema: type: string example: "+14155552671" responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PhoneNumberResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/phone-numbers status: 400 timestamp: 2026-05-05T10:06:46.067804 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/phone-numbers status: 401 timestamp: 2026-05-05T10:06:46.067828 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/phone-numbers status: 403 timestamp: 2026-05-05T10:06:46.067835 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/phone-numbers status: 404 timestamp: 2026-05-05T10:06:46.067841 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/phone-numbers status: 500 timestamp: 2026-05-05T10:06:46.067852 delete: tags: - Phone Numbers summary: Delete Phone Number description: "Permanently removes a phone number from your account — provisioned\ \ numbers are released to the carrier, BYO numbers remain with your telecom\ \ provider. Cannot be undone. Returns 204 No Content on success." operationId: deletePhoneNumber parameters: - name: phoneNumber in: path description: "Phone number to delete, in +E.164 format. Obtained from the\ \ sipPhoneNumber field in the Create, Import, or List Phone Numbers response." required: true schema: type: string example: "+14155552671" responses: "200": description: OK "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/phone-numbers status: 400 timestamp: 2026-05-05T10:06:46.153723 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/phone-numbers status: 401 timestamp: 2026-05-05T10:06:46.153741 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/phone-numbers status: 403 timestamp: 2026-05-05T10:06:46.153748 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/phone-numbers status: 404 timestamp: 2026-05-05T10:06:46.153753 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/phone-numbers status: 500 timestamp: 2026-05-05T10:06:46.153763 patch: tags: - Phone Numbers summary: Update Phone Number description: Partially updates the configuration of an existing phone number. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated phone number record. operationId: updatePhoneNumber parameters: - name: phoneNumber in: path description: "Phone number to update, in +E.164 format. Obtained from the\ \ sipPhoneNumber field in the Create, Import, or List Phone Numbers response." required: true schema: type: string example: "+14155552671" requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdatePhoneNumberRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PhoneNumberResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/phone-numbers status: 400 timestamp: 2026-05-05T10:06:45.943193 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/phone-numbers status: 401 timestamp: 2026-05-05T10:06:45.943218 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/phone-numbers status: 403 timestamp: 2026-05-05T10:06:45.943226 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/phone-numbers status: 404 timestamp: 2026-05-05T10:06:45.943231 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/phone-numbers status: 500 timestamp: 2026-05-05T10:06:45.943243 # Agent APIs /v1/agents: get: tags: - Single Prompt Agents summary: List Agents description: Retrieve a paginated list of all single prompt agents available in the account along with their details and configurations. operationId: listSinglePromptAgents parameters: - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 - name: size in: query description: Number of single prompt changes to retrieve per page. Must be 1 or greater. required: false schema: type: integer format: int32 default: 10 responses: "200": description: OK content: '*/*': schema: $ref: '#/components/schemas/PaginatedResponseCreateAgentResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/agents status: 400 timestamp: 2026-05-04T14:44:41.742382 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/agents status: 401 timestamp: 2026-05-04T14:44:41.742406 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/agents status: 403 timestamp: 2026-05-04T14:44:41.742410 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/agents status: 404 timestamp: 2026-05-04T14:44:41.742415 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/agents status: 500 timestamp: 2026-05-04T14:44:41.742421 post: tags: - Agents summary: Create Agent description: "Creates a new single prompt agent with the specified configuration,\ \ including system prompt and agent settings. Returns the created agent including\ \ its agentId, which is required for all subsequent update, call, and simulation\ \ operations." operationId: createSinglePromptAgent requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAgentRequest' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/CreateAgentResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/agents status: 400 timestamp: 2026-05-05T10:06:45.920565 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/agents status: 401 timestamp: 2026-05-05T10:06:45.920589 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/agents status: 403 timestamp: 2026-05-05T10:06:45.920597 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/agents status: 404 timestamp: 2026-05-05T10:06:45.920604 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/agents status: 500 timestamp: 2026-05-05T10:06:45.920616 /v1/agents/{agentId}: get: tags: - Single Prompt Agents summary: Get Agent description: "Retrieves the full details of a single prompt agent, along with agent settings." operationId: getSinglePromptAgent parameters: - name: agentId in: path description: Unique identifier of the agent to be retrieved. required: true schema: type: string responses: "200": description: OK content: '*/*': schema: $ref: '#/components/schemas/CreateAgentResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/agents status: 400 timestamp: 2026-05-04T14:44:41.760886 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/agents status: 401 timestamp: 2026-05-04T14:44:41.760903 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/agents status: 403 timestamp: 2026-05-04T14:44:41.760906 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/agents status: 404 timestamp: 2026-05-04T14:44:41.760909 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/agents status: 500 timestamp: 2026-05-04T14:44:41.760914 delete: tags: - Single Prompt Agents summary: Delete Agent description: Permanently deletes an agent from your account. Cannot be undone. operationId: deletePhoneNumber_1 parameters: - name: agentId in: path description: Unique identifier of the agent to be deleted. required: true schema: type: string responses: "204": description: No Content "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/agents status: 400 timestamp: 2026-05-04T14:44:41.768626 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/agents status: 401 timestamp: 2026-05-04T14:44:41.768642 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/agents status: 403 timestamp: 2026-05-04T14:44:41.768652 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/agents status: 404 timestamp: 2026-05-04T14:44:41.768655 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/agents status: 500 timestamp: 2026-05-04T14:44:41.768660 patch: tags: - Agents summary: Update Agent description: Partially updates an existing agent by agentId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated agent record. operationId: updateSinglePromptAgent parameters: - name: agentId in: path description: Unique identifier of the agent to update. required: true schema: type: string example: agent_IqmljBh8eSEGAqKd requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAgentRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/CreateAgentResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/agents status: 400 timestamp: 2026-05-05T10:06:46.023641 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/agents status: 401 timestamp: 2026-05-05T10:06:46.023668 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/agents status: 403 timestamp: 2026-05-05T10:06:46.023677 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/agents status: 404 timestamp: 2026-05-05T10:06:46.023683 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/agents status: 500 timestamp: 2026-05-05T10:06:46.023697 /v1/agents/{agentId}/tools: get: tags: - Agents summary: List Agent Tools description: Retrieve a paginated list of all the tools associated with the agent. operationId: listAgentTools parameters: - name: agentId in: path description: Unique identifier of the agent to be retrieved. required: true schema: type: string example: agent_72e72 - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of single prompt agents to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseAgentToolResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/agents status: 400 timestamp: 2026-09-08T12:22:37.691103 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/agents status: 401 timestamp: 2026-09-08T12:22:37.691130 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/agents status: 403 timestamp: 2026-09-08T12:22:37.691138 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/agents status: 404 timestamp: 2026-09-08T12:22:37.691149 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/agents status: 500 timestamp: 2026-09-08T12:22:37.691156 # Conversational Agent APIs /v1/conversational-agents: post: tags: - Conversational Agents summary: Create conversational Agent description: "Creates a new conversational agent from the given nodes and agent\ \ settings. Every node is connected through the nodeName referenced by its\ \ edges, and the conversation starts at startNodeName, defaulting to the first\ \ node of the request. Returns the created agent including its agentId, which\ \ is required for all subsequent update, call, and simulation operations." operationId: createConversationalAgent requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateConversationalAgentRequest' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/ConversationalAgentResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/conversational-agents status: 400 timestamp: 2026-09-28T16:34:43.436338 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/conversational-agents status: 401 timestamp: 2026-09-28T16:34:43.436367 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/conversational-agents status: 403 timestamp: 2026-09-28T16:34:43.436373 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/conversational-agents status: 404 timestamp: 2026-09-28T16:34:43.436378 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/conversational-agents status: 500 timestamp: 2026-09-28T16:34:43.436382 /v1/conversational-agents/{agentId}: get: tags: - Conversational Agents summary: Get conversational Agent description: "Get a conversational agent, along with agent settings" operationId: getSinglePromptAgent parameters: - name: agentId in: path description: Unique identifier of the agent to be retrieved. required: true schema: type: string example: agent_72e72 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/ConversationalAgentResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/conversational-agents status: 400 timestamp: 2026-09-18T20:53:02.761085 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/conversational-agents status: 401 timestamp: 2026-09-18T20:53:02.761106 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/conversational-agents status: 403 timestamp: 2026-09-18T20:53:02.761109 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/conversational-agents status: 404 timestamp: 2026-09-18T20:53:02.761112 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/conversational-agents status: 500 timestamp: 2026-09-18T20:53:02.761115 patch: tags: - Conversational Agents summary: Update conversational Agent description: "Partially updates an existing conversational agent by agentId.\ \ Only the fields provided in the request body are updated — omitted fields\ \ remain unchanged. Nodes carrying a nodeId are updated, while nodes without\ \ one are created and connected through the nextNodeId or nextNodeName referenced\ \ by their edges. Returns the updated agent including all of its nodes and\ \ agent settings." operationId: updateConversationalAgent parameters: - name: agentId in: path description: Unique identifier of the agent to update. required: true schema: type: string example: agent_72e72 requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateConversationalAgentRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/ConversationalAgentResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/conversational-agents status: 400 timestamp: 2026-09-28T16:34:43.684619 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/conversational-agents status: 401 timestamp: 2026-09-28T16:34:43.684636 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/conversational-agents status: 403 timestamp: 2026-09-28T16:34:43.684639 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/conversational-agents status: 404 timestamp: 2026-09-28T16:34:43.684642 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/conversational-agents status: 500 timestamp: 2026-09-28T16:34:43.684644 # Campaign APIs /v1/campaigns: get: tags: - Campaigns summary: List Campaigns description: "Returns a paginated list of campaigns for the account, sorted\ \ by most recently created first. Use the status parameter to filter by lifecycle\ \ state. Use page and size to navigate through results." operationId: listCampaigns parameters: - name: status in: query description: "Filter campaigns by their current lifecycle state. Accepted\ \ values: 'live', 'scheduled', 'paused', 'completed'. Omit to return campaigns\ \ in all states." required: false schema: type: string example: live - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of campaigns to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseCampaignResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/campaigns status: 400 timestamp: 2026-05-05T10:06:46.136464 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/campaigns status: 401 timestamp: 2026-05-05T10:06:46.136495 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/campaigns status: 403 timestamp: 2026-05-05T10:06:46.136506 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/campaigns status: 404 timestamp: 2026-05-05T10:06:46.136513 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/campaigns status: 500 timestamp: 2026-05-05T10:06:46.136528 post: tags: - Campaigns summary: Create Campaign description: "Creates an outbound call campaign with the specified agent, caller\ \ number, and CSV contact list. Set isScheduled=true with scheduledDate, scheduledTime,\ \ and scheduledTimezone to defer launch. Returns the created campaign, including\ \ its campaignId." operationId: createCampaign requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/CreateCampaignRequest' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/CampaignResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/campaigns status: 400 timestamp: 2026-05-05T10:06:45.887521 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/campaigns status: 401 timestamp: 2026-05-05T10:06:45.887546 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/campaigns status: 403 timestamp: 2026-05-05T10:06:45.887555 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/campaigns status: 404 timestamp: 2026-05-05T10:06:45.887560 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/campaigns status: 500 timestamp: 2026-05-05T10:06:45.887573 /v1/campaigns/{campaignId}: get: tags: - Campaigns summary: Get Campaign description: "Retrieves the full details of a single campaign by campaignId.\ \ Returns current status, schedule configuration, assigned agent, caller number,\ \ and any CSV upload errors." operationId: getCampaign parameters: - name: campaignId in: path description: Unique identifier of the campaign to retrieve. required: true schema: type: string example: camp_XiQEBcj9cc5TFRB4 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/CampaignResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/campaigns status: 400 timestamp: 2026-05-05T10:06:46.145710 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/campaigns status: 401 timestamp: 2026-05-05T10:06:46.145740 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/campaigns status: 403 timestamp: 2026-05-05T10:06:46.145749 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/campaigns status: 404 timestamp: 2026-05-05T10:06:46.145758 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/campaigns status: 500 timestamp: 2026-05-05T10:06:46.145773 delete: tags: - Campaigns summary: Delete Campaign description: Permanently deletes a campaign by campaignId. Cannot be undone — the campaign must have no associated calls before deletion. Returns 204 No Content on success. operationId: deleteCampaign parameters: - name: campaignId in: path description: Unique identifier of the campaign to delete. required: true schema: type: string example: camp_XiQEBcj9cc5TFRB4 responses: "200": description: OK "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/campaigns status: 400 timestamp: 2026-05-05T10:06:46.162168 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/campaigns status: 401 timestamp: 2026-05-05T10:06:46.162186 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/campaigns status: 403 timestamp: 2026-05-05T10:06:46.162192 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/campaigns status: 404 timestamp: 2026-05-05T10:06:46.162197 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/campaigns status: 500 timestamp: 2026-05-05T10:06:46.162205 patch: tags: - Campaigns summary: Update Campaign description: Partially updates an existing campaign by campaignId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated campaign record. operationId: updateCampaign parameters: - name: campaignId in: path description: Unique identifier of the campaign to update. required: true schema: type: string example: camp_XiQEBcj9cc5TFRB4 requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateCampaignRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/CampaignResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/campaigns status: 400 timestamp: 2026-05-05T10:06:45.996208 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/campaigns status: 401 timestamp: 2026-05-05T10:06:45.996237 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/campaigns status: 403 timestamp: 2026-05-05T10:06:45.996245 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/campaigns status: 404 timestamp: 2026-05-05T10:06:45.996252 "409": description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Conflict message: Conflict with the current state of the resource path: /v1/campaigns status: 409 timestamp: 2026-05-05T10:06:45.996257 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/campaigns status: 500 timestamp: 2026-05-05T10:06:45.996262 # Integrations APIs /v1/integrations: get: tags: - Integrations summary: List Integrations description: "Returns a paginated list of integrations registered on the account,\ \ sorted by most recently created first. Use the provider parameter to filter\ \ by integration type. Use page and size to navigate through results." operationId: listIntegrations parameters: - name: provider in: query description: "Filter integrations by provider type (e.g. shopify, cal_com).\ \ Omit to return integrations for all providers." required: false schema: type: string example: shopify - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of integrations to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseIntegrationResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/integrations status: 400 timestamp: 2026-05-05T10:06:46.091942 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/integrations status: 401 timestamp: 2026-05-05T10:06:46.091966 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/integrations status: 403 timestamp: 2026-05-05T10:06:46.091972 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/integrations status: 404 timestamp: 2026-05-05T10:06:46.091978 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/integrations status: 500 timestamp: 2026-05-05T10:06:46.091989 post: tags: - Integrations summary: Create Integration description: "Registers a new third-party integration for your account. Supply\ \ the provider type (e.g. shopify, cal_com) along with an optional friendly\ \ name and description. Returns the created integration including its integrationId,\ \ which is required for all subsequent auth and tool operations." operationId: createIntegration requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateIntegrationRequest' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/IntegrationResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/integrations status: 400 timestamp: 2026-05-05T10:06:45.767619 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/integrations status: 401 timestamp: 2026-05-05T10:06:45.767653 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/integrations status: 403 timestamp: 2026-05-05T10:06:45.767673 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/integrations status: 404 timestamp: 2026-05-05T10:06:45.767683 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/integrations status: 500 timestamp: 2026-05-05T10:06:45.767701 /v1/integrations/{integrationId}: get: tags: - Integrations summary: Get Integration description: "Retrieves the full details of a single integration by integrationId.\ \ Returns the provider type, friendly name, description, and current status\ \ of the integration." operationId: getIntegration parameters: - name: integrationId in: path description: Unique identifier of the integration to retrieve. required: true schema: type: string example: intg_AuUKK371Spr5 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/IntegrationResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/integrations status: 400 timestamp: 2026-05-05T10:06:46.100229 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/integrations status: 401 timestamp: 2026-05-05T10:06:46.100250 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/integrations status: 403 timestamp: 2026-05-05T10:06:46.100257 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/integrations status: 404 timestamp: 2026-05-05T10:06:46.100262 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/integrations status: 500 timestamp: 2026-05-05T10:06:46.100273 delete: tags: - Integrations summary: Delete Integration description: "Permanently deletes an integration by integrationId, including\ \ all associated auth credentials and tools. Cannot be undone. Returns 204\ \ No Content on success." operationId: deleteIntegration parameters: - name: integrationId in: path description: Unique identifier of the integration to delete. required: true schema: type: string example: intg_AuUKK371Spr5 responses: "200": description: OK "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/integrations status: 400 timestamp: 2026-05-05T10:06:46.156792 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/integrations status: 401 timestamp: 2026-05-05T10:06:46.156813 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/integrations status: 403 timestamp: 2026-05-05T10:06:46.156826 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/integrations status: 404 timestamp: 2026-05-05T10:06:46.156834 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/integrations status: 500 timestamp: 2026-05-05T10:06:46.156909 patch: tags: - Integrations summary: Update Integration description: Partially updates an existing integration by integrationId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated integration record. operationId: updateIntegration parameters: - name: integrationId in: path description: Unique identifier of the integration to update. required: true schema: type: string example: intg_AuUKK371Spr5 requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateIntegrationRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/IntegrationResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/integrations status: 400 timestamp: 2026-05-05T10:06:45.961495 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/integrations status: 401 timestamp: 2026-05-05T10:06:45.961521 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/integrations status: 403 timestamp: 2026-05-05T10:06:45.961528 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/integrations status: 404 timestamp: 2026-05-05T10:06:45.961535 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/integrations status: 500 timestamp: 2026-05-05T10:06:45.961545 # Integration Auth APIs /v1/integrations/{integrationId}/auth: get: tags: - Integration Auth summary: List Integration Auth description: "Returns a paginated list of auth records for a given integration,\ \ sorted by most recently created first. Use the authType parameter to filter\ \ by credential type. Use page and size to navigate through results." operationId: listAuth parameters: - name: integrationId in: path description: Unique identifier for the integration required: true schema: type: string example: intg_AuUKK371Spr5 - name: authType in: query description: "Filter auth records by credential type. Accepted values: 'API_KEY',\ \ 'BASIC', 'BEARER'. Omit to return auth records of all types." required: false schema: type: string example: API_KEY - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of auth records to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseIntegrationAuthResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: "/v1/integrations/{integrationId}/auth" status: 400 timestamp: 2026-05-05T10:06:46.120637 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: "/v1/integrations/{integrationId}/auth" status: 401 timestamp: 2026-05-05T10:06:46.120675 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: "/v1/integrations/{integrationId}/auth" status: 403 timestamp: 2026-05-05T10:06:46.120682 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: "/v1/integrations/{integrationId}/auth" status: 404 timestamp: 2026-05-05T10:06:46.120688 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: "/v1/integrations/{integrationId}/auth" status: 500 timestamp: 2026-05-05T10:06:46.120699 post: tags: - Integration Auth summary: Create Integration Auth description: "Creates and stores authentication credentials for an integration.\ \ Supports three auth types: API Key, Basic auth, and Bearer token. Returns\ \ the created auth record including its authId, which is required for subsequent\ \ get, update, and delete calls." operationId: createAuth parameters: - name: integrationId in: path description: Unique identifier for the integration required: true schema: type: string example: intg_AuUKK371Spr5 requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateIntegrationAuthRequest' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/IntegrationAuthResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: "/v1/integrations/{integrationId}/auth" status: 400 timestamp: 2026-05-05T10:06:45.814862 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: "/v1/integrations/{integrationId}/auth" status: 401 timestamp: 2026-05-05T10:06:45.814895 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: "/v1/integrations/{integrationId}/auth" status: 403 timestamp: 2026-05-05T10:06:45.814906 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: "/v1/integrations/{integrationId}/auth" status: 404 timestamp: 2026-05-05T10:06:45.814915 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: "/v1/integrations/{integrationId}/auth" status: 500 timestamp: 2026-05-05T10:06:45.814931 /v1/integrations/{integrationId}/auth/{authId}: get: tags: - Integration Auth summary: Get Integration Auth description: "Retrieves the full details of a single auth record by authId.\ \ Returns the auth type, credential metadata, and associated integration.\ \ Sensitive credential values are not returned after creation." operationId: getAuth parameters: - name: integrationId in: path description: Unique identifier for the integration required: true schema: type: string example: intg_AuUKK371Spr5 - name: authId in: path description: Unique identifier for the auth record required: true schema: type: string example: auth_P3kNz7Yv1Qm9 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/IntegrationAuthResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: "/v1/integrations/{integrationId}/auth" status: 400 timestamp: 2026-05-05T10:06:46.124304 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: "/v1/integrations/{integrationId}/auth" status: 401 timestamp: 2026-05-05T10:06:46.124327 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: "/v1/integrations/{integrationId}/auth" status: 403 timestamp: 2026-05-05T10:06:46.124333 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: "/v1/integrations/{integrationId}/auth" status: 404 timestamp: 2026-05-05T10:06:46.124339 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: "/v1/integrations/{integrationId}/auth" status: 500 timestamp: 2026-05-05T10:06:46.124348 delete: tags: - Integration Auth summary: Delete Integration Auth description: Permanently deletes an auth record by authId. Cannot be undone — any tools referencing this auth record will lose the ability to authenticate. Returns 204 No Content on success. operationId: deleteAuth parameters: - name: integrationId in: path description: Unique identifier for the integration required: true schema: type: string example: intg_AuUKK371Spr5 - name: authId in: path description: Unique identifier for the auth record required: true schema: type: string example: auth_P3kNz7Yv1Qm9 responses: "200": description: OK "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: "/v1/integrations/{integrationId}/auth" status: 400 timestamp: 2026-05-05T10:06:46.160597 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: "/v1/integrations/{integrationId}/auth" status: 401 timestamp: 2026-05-05T10:06:46.160618 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: "/v1/integrations/{integrationId}/auth" status: 403 timestamp: 2026-05-05T10:06:46.160631 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: "/v1/integrations/{integrationId}/auth" status: 404 timestamp: 2026-05-05T10:06:46.160640 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: "/v1/integrations/{integrationId}/auth" status: 500 timestamp: 2026-05-05T10:06:46.160660 patch: tags: - Integration Auth summary: Update Integration Auth description: Partially updates an existing auth record by authId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated auth record. operationId: updateAuth parameters: - name: integrationId in: path description: Unique identifier for the integration required: true schema: type: string example: intg_AuUKK371Spr5 - name: authId in: path description: Unique identifier for the auth record required: true schema: type: string example: auth_P3kNz7Yv1Qm9 requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateIntegrationAuthRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/IntegrationAuthResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: "/v1/integrations/{integrationId}/auth" status: 400 timestamp: 2026-05-05T10:06:45.984006 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: "/v1/integrations/{integrationId}/auth" status: 401 timestamp: 2026-05-05T10:06:45.984030 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: "/v1/integrations/{integrationId}/auth" status: 403 timestamp: 2026-05-05T10:06:45.984039 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: "/v1/integrations/{integrationId}/auth" status: 404 timestamp: 2026-05-05T10:06:45.984044 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: "/v1/integrations/{integrationId}/auth" status: 500 timestamp: 2026-05-05T10:06:45.984056 # Integration Tools APIs /v1/integrations/{integrationId}/tools: get: tags: - Integration Tools summary: List Tools description: "Returns a paginated list of tools registered under an integration,\ \ sorted by most recently created first. Use the status parameter to filter\ \ by tool state. Use page and size to navigate through results." operationId: listIntegrationTools parameters: - name: integrationId in: path description: Unique identifier of the integration whose tools are to be listed. required: true schema: type: string example: intg_AuUKK371Spr5 - name: status in: query description: "Filter tools by their current state. Accepted values: 'active',\ \ 'inactive'. Omit to return tools in all states." required: false schema: type: string example: active - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of tools to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseIntegrationToolResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: "/v1/integrations/{integrationId}/tools" status: 400 timestamp: 2026-05-05T10:06:46.108833 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: "/v1/integrations/{integrationId}/tools" status: 401 timestamp: 2026-05-05T10:06:46.108857 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: "/v1/integrations/{integrationId}/tools" status: 403 timestamp: 2026-05-05T10:06:46.108864 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: "/v1/integrations/{integrationId}/tools" status: 404 timestamp: 2026-05-05T10:06:46.108873 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: "/v1/integrations/{integrationId}/tools" status: 500 timestamp: 2026-05-05T10:06:46.108882 post: tags: - Integration Tools summary: Create Tool description: "Creates a new API tool under the specified integration. Define\ \ the HTTP endpoint, method, and parameter schema the agent will use when\ \ invoking the tool. Returns the created tool including its toolId, which\ \ is required for subsequent get, update, delete, and execute calls." operationId: createIntegrationTool parameters: - name: integrationId in: path description: Unique identifier of the integration to create the tool under. required: true schema: type: string example: intg_AuUKK371Spr5 requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateIntegrationToolRequest' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/IntegrationToolResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: "/v1/integrations/{integrationId}/tools" status: 400 timestamp: 2026-05-05T10:06:45.788820 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: "/v1/integrations/{integrationId}/tools" status: 401 timestamp: 2026-05-05T10:06:45.788851 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: "/v1/integrations/{integrationId}/tools" status: 403 timestamp: 2026-05-05T10:06:45.788862 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: "/v1/integrations/{integrationId}/tools" status: 404 timestamp: 2026-05-05T10:06:45.788873 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: "/v1/integrations/{integrationId}/tools" status: 500 timestamp: 2026-05-05T10:06:45.788888 /v1/integrations/{integrationId}/tools/{toolId}: get: tags: - Integration Tools summary: Get Tool description: "Retrieves the full configuration of a single tool by toolId. Returns\ \ the tool's endpoint, HTTP method, parameter schema, and access type." operationId: getIntegrationTool parameters: - name: integrationId in: path description: Unique identifier of the integration to which the tool belongs. required: true schema: type: string example: intg_AuUKK371Spr5 - name: toolId in: path description: Unique identifier of the tool to retrieve. required: true schema: type: string example: tool_X9pLm2Wq8Rt3 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/IntegrationToolResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: "/v1/integrations/{integrationId}/tools" status: 400 timestamp: 2026-05-05T10:06:46.113834 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: "/v1/integrations/{integrationId}/tools" status: 401 timestamp: 2026-05-05T10:06:46.113853 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: "/v1/integrations/{integrationId}/tools" status: 403 timestamp: 2026-05-05T10:06:46.113861 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: "/v1/integrations/{integrationId}/tools" status: 404 timestamp: 2026-05-05T10:06:46.113866 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: "/v1/integrations/{integrationId}/tools" status: 500 timestamp: 2026-05-05T10:06:46.113877 delete: tags: - Integration Tools summary: Delete Tool description: Permanently deletes a tool by toolId — cannot be undone. Any agent using this tool will lose access immediately. Returns 204 No Content on success. operationId: deleteIntegrationTool parameters: - name: integrationId in: path description: Unique identifier of the integration to which the tool belongs. required: true schema: type: string example: intg_AuUKK371Spr5 - name: toolId in: path description: Unique identifier of the tool to delete. required: true schema: type: string example: tool_X9pLm2Wq8Rt3 responses: "200": description: OK "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: "/v1/integrations/{integrationId}/tools" status: 400 timestamp: 2026-05-05T10:06:46.158575 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: "/v1/integrations/{integrationId}/tools" status: 401 timestamp: 2026-05-05T10:06:46.158590 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: "/v1/integrations/{integrationId}/tools" status: 403 timestamp: 2026-05-05T10:06:46.158597 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: "/v1/integrations/{integrationId}/tools" status: 404 timestamp: 2026-05-05T10:06:46.158602 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: "/v1/integrations/{integrationId}/tools" status: 500 timestamp: 2026-05-05T10:06:46.158611 patch: tags: - Integration Tools summary: Update Tool description: Partially updates an existing tool by toolId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated tool record. operationId: updateIntegrationTool parameters: - name: integrationId in: path description: Unique identifier of the integration to which the tool belongs. required: true schema: type: string example: intg_AuUKK371Spr5 - name: toolId in: path description: Unique identifier of the tool to update. required: true schema: type: string example: tool_X9pLm2Wq8Rt3 requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateIntegrationToolRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/IntegrationToolResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: "/v1/integrations/{integrationId}/tools" status: 400 timestamp: 2026-05-05T10:06:45.974831 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: "/v1/integrations/{integrationId}/tools" status: 401 timestamp: 2026-05-05T10:06:45.974853 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: "/v1/integrations/{integrationId}/tools" status: 403 timestamp: 2026-05-05T10:06:45.974861 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: "/v1/integrations/{integrationId}/tools" status: 404 timestamp: 2026-05-05T10:06:45.974867 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: "/v1/integrations/{integrationId}/tools" status: 500 timestamp: 2026-05-05T10:06:45.974879 /v1/integrations/{integrationId}/tools/{toolId}/execute: post: tags: - Integration Tools summary: Execute Tool description: "Executes a tool against its configured third-party API using the\ \ supplied placeholder values. Auth credentials are resolved automatically;\ \ specify authId to select specific credentials when multiple exist. Optionally\ \ set saveAsMock to persist the live request/response as a named mock, or\ \ useMockToolDataId to return a stored mock without calling the third-party\ \ API. Returns the response body, status code, and optional mockToolDataId." operationId: executeIntegrationTool parameters: - name: integrationId in: path description: Unique identifier of the integration to which the tool belongs. required: true schema: type: string example: intg_AuUKK371Spr5 - name: toolId in: path description: Unique identifier of the tool to execute. required: true schema: type: string example: tool_X9pLm2Wq8Rt3 requestBody: content: application/json: schema: $ref: '#/components/schemas/ExecuteToolRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/ExecuteToolResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: "/v1/integrations/{integrationId}/tools" status: 400 timestamp: 2026-10-14T11:41:38.586993 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: "/v1/integrations/{integrationId}/tools" status: 401 timestamp: 2026-10-14T11:41:38.587015 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: "/v1/integrations/{integrationId}/tools" status: 403 timestamp: 2026-10-14T11:41:38.587025 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: "/v1/integrations/{integrationId}/tools" status: 404 timestamp: 2026-10-14T11:41:38.587033 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: "/v1/integrations/{integrationId}/tools" status: 500 timestamp: 2026-10-14T11:41:38.587040 # Webhooks APIs /v1/webhooks: get: tags: - Webhooks summary: List Webhooks description: "Returns a paginated list of webhooks for the account, sorted by\ \ most recently created first. Use agentId to filter by agent and active to\ \ filter by enabled/disabled status. Use page and size to navigate through\ \ results." operationId: listWebhook parameters: - name: agentId in: query description: Filter webhooks by the agent they are scoped to. Obtained from the agentId field in the agent list or creation response. Omit to return webhooks across all agents. required: false schema: type: string example: agent_D5D0p7TUs66TTAEAx - name: active in: query description: Filter webhooks by their active status. true returns only webhooks currently enabled and receiving event deliveries. false returns only disabled webhooks. Defaults to true. required: false schema: type: boolean default: true example: true - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of webhooks to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseWebhookResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/webhooks status: 400 timestamp: 2026-05-05T10:06:46.038166 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/webhooks status: 401 timestamp: 2026-05-05T10:06:46.038192 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/webhooks status: 403 timestamp: 2026-05-05T10:06:46.038215 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/webhooks status: 404 timestamp: 2026-05-05T10:06:46.038222 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/webhooks status: 500 timestamp: 2026-05-05T10:06:46.038234 post: tags: - Webhooks summary: Create Webhook description: Registers a new webhook to receive real-time event notifications on your HTTPS endpoint. The webhook is scoped to a single agent and fires only for the event types you specify. Returns the created webhook including its webhookId and HMAC secret — store the secret securely as it is only returned once. operationId: registerWebhook requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateWebhookRequest' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/WebhookResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/webhooks status: 400 timestamp: 2026-05-05T10:06:45.656578 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/webhooks status: 401 timestamp: 2026-05-05T10:06:45.656698 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/webhooks status: 403 timestamp: 2026-05-05T10:06:45.656713 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/webhooks status: 404 timestamp: 2026-05-05T10:06:45.656723 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/webhooks status: 500 timestamp: 2026-05-05T10:06:45.656742 /v1/webhooks/{webhookId}: get: tags: - Webhooks summary: Get Webhook description: "Retrieves the full configuration of a single webhook by webhookId.\ \ Returns the target URL, scoped agent, subscribed event types, and active\ \ status. The HMAC secret is not returned after creation — store it securely\ \ when the webhook is first created." operationId: getWebhook parameters: - name: webhookId in: path description: Unique identifier of the webhook to retrieve. Obtained from the webhookId field in the Create Webhook or List Webhooks response. required: true schema: type: string example: wh_BUbkx3PsbzQm5V10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/WebhookResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/webhooks status: 400 timestamp: 2026-05-05T10:06:46.042245 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/webhooks status: 401 timestamp: 2026-05-05T10:06:46.042269 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/webhooks status: 403 timestamp: 2026-05-05T10:06:46.042292 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/webhooks status: 404 timestamp: 2026-05-05T10:06:46.042298 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/webhooks status: 500 timestamp: 2026-05-05T10:06:46.042312 delete: tags: - Webhooks summary: Delete Webhook description: Permanently removes a webhook by webhookId. Cannot be undone — no further event deliveries will be attempted to the registered URL. Returns 204 No Content on success. operationId: deleteWebhook parameters: - name: webhookId in: path description: Unique identifier of the webhook to delete. Obtained from the webhookId field in the Create Webhook or List Webhooks response. required: true schema: type: string example: wh_BUbkx3PsbzQm5V10 responses: "200": description: OK "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/webhooks status: 400 timestamp: 2026-05-05T10:06:46.150216 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/webhooks status: 401 timestamp: 2026-05-05T10:06:46.150249 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/webhooks status: 403 timestamp: 2026-05-05T10:06:46.150261 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/webhooks status: 404 timestamp: 2026-05-05T10:06:46.150272 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/webhooks status: 500 timestamp: 2026-05-05T10:06:46.150289 # Test Case APIs /v1/test-cases: get: tags: - Test Cases summary: List Test Cases description: "Returns a paginated list of simulation test cases for the specified\ \ agent, sorted by most recently created first. Use page and size to navigate\ \ through results." operationId: listTestCases parameters: - name: agentId in: query description: Unique identifier of the agent whose test cases are to be listed. required: true schema: type: string example: agent_IqmljBh8eSEGAqKd - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of test cases to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseTestCaseResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/test-cases status: 400 timestamp: 2026-09-07T03:34:25.441810 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/test-cases status: 401 timestamp: 2026-09-07T03:34:25.441833 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/test-cases status: 403 timestamp: 2026-09-07T03:34:25.441840 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/test-cases status: 404 timestamp: 2026-09-07T03:34:25.441845 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/test-cases status: 500 timestamp: 2026-09-07T03:34:25.441849 post: tags: - Test Cases summary: Create Test Case description: "Creates a simulation test case for the specified agent. Define\ \ the scenario using user persona, goals, and evaluation criteria. Returns\ \ the created test case, including its testCaseId for subsequent get, update,\ \ delete, and batch-run calls." operationId: createTestCase requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTestCaseRequest' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/TestCaseResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/test-cases status: 400 timestamp: 2026-09-07T03:34:24.965137 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/test-cases status: 401 timestamp: 2026-09-07T03:34:24.965173 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/test-cases status: 403 timestamp: 2026-09-07T03:34:24.965184 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/test-cases status: 404 timestamp: 2026-09-07T03:34:24.965195 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/test-cases status: 500 timestamp: 2026-09-07T03:34:24.965204 /v1/test-cases/{testCaseId}: get: tags: - Test Cases summary: Get Test Case description: "Retrieves the full details of a single simulation test case by\ \ testCaseId. Returns the conversation scenario definition, including the\ \ user persona, goals, evaluation criteria, and current status." operationId: getTestCase parameters: - name: testCaseId in: path description: Unique identifier of the test case to retrieve. Obtained from the testCaseId field in the Create Test Case or List Test Cases response. required: true schema: type: string example: tc_HaDxmGfwb8MZLlKM - name: agentId in: query description: Unique identifier of the agent to which the test case belongs. required: true schema: type: string example: agent_IqmljBh8eSEGAqKd responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/TestCaseResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/test-cases status: 400 timestamp: 2026-09-07T03:34:25.447169 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/test-cases status: 401 timestamp: 2026-09-07T03:34:25.447190 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/test-cases status: 403 timestamp: 2026-09-07T03:34:25.447196 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/test-cases status: 404 timestamp: 2026-09-07T03:34:25.447202 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/test-cases status: 500 timestamp: 2026-09-07T03:34:25.447207 delete: tags: - Test Cases summary: Delete Test Case description: Permanently deletes a simulation test case by testCaseId. Cannot be undone — the test case will no longer be available for future batch runs. Returns 204 No Content on success. operationId: deleteTestCase parameters: - name: testCaseId in: path description: Unique identifier of the test case to delete. Obtained from the testCaseId field in the Create Test Case or List Test Cases response. required: true schema: type: string example: tc_HaDxmGfwb8MZLlKM responses: "200": description: OK "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/test-cases status: 400 timestamp: 2026-09-07T03:34:25.588232 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/test-cases status: 401 timestamp: 2026-09-07T03:34:25.588246 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/test-cases status: 403 timestamp: 2026-09-07T03:34:25.588252 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/test-cases status: 404 timestamp: 2026-09-07T03:34:25.588257 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/test-cases status: 500 timestamp: 2026-09-07T03:34:25.588261 patch: tags: - Test Cases summary: Update Test Case description: Partially updates an existing simulation test case by testCaseId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated test case record. operationId: patchUpdateTestCase parameters: - name: testCaseId in: path description: Unique identifier of the test case to update. Obtained from the testCaseId field in the Create Test Case or List Test Cases response. required: true schema: type: string example: tc_HaDxmGfwb8MZLlKM requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateTestCaseRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/TestCaseResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/test-cases status: 400 timestamp: 2026-09-07T03:34:25.290780 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/test-cases status: 401 timestamp: 2026-09-07T03:34:25.290804 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/test-cases status: 403 timestamp: 2026-09-07T03:34:25.290811 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/test-cases status: 404 timestamp: 2026-09-07T03:34:25.290816 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/test-cases status: 500 timestamp: 2026-09-07T03:34:25.290821 # Batch Run APIs /v1/batch-runs: get: tags: - Batch Runs summary: List Batch Runs description: "Returns a paginated list of batch runs for the specified agent,\ \ sorted by most recently created first. Use page and size to navigate through\ \ results." operationId: listBatches parameters: - name: agentId in: query description: Unique identifier of the agent whose batch runs are to be listed. required: true schema: type: string example: agent_IqmljBh8eSEGAqKd - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of batch runs to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseBatchResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/batch-runs status: 400 timestamp: 2026-05-05T10:06:43.879953 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/batch-runs status: 401 timestamp: 2026-05-05T10:06:43.879979 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/batch-runs status: 403 timestamp: 2026-05-05T10:06:43.879985 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/batch-runs status: 404 timestamp: 2026-05-05T10:06:43.879992 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/batch-runs status: 500 timestamp: 2026-05-05T10:06:43.880001 post: tags: - Batch Runs summary: Create Batch Run description: "Triggers a new batch run by executing the specified test cases\ \ in parallel against the selected agent. Returns the created batch including\ \ its batchId, which is required for subsequent get and list test-run calls." operationId: createBatchRun requestBody: content: application/json: schema: $ref: '#/components/schemas/BatchRunRequest' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/CreateBatchRunResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/batch-runs status: 400 timestamp: 2026-05-05T10:06:43.702204 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/batch-runs status: 401 timestamp: 2026-05-05T10:06:43.702245 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/batch-runs status: 403 timestamp: 2026-05-05T10:06:43.702255 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/batch-runs status: 404 timestamp: 2026-05-05T10:06:43.702262 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/batch-runs status: 500 timestamp: 2026-05-05T10:06:43.702276 /v1/batch-runs/{batchId}: get: tags: - Batch Runs summary: Get Batch Run description: "Retrieves the full details of a batch run by batchId, scoped to\ \ the specified agent. Returns overall batch status, test case count, pass/fail\ \ summary, and individual run results." operationId: getBatch parameters: - name: batchId in: path description: The unique identifier of the batch run to retrieve. required: true schema: type: string example: batch_KidCyVw5gJN87n5S - name: agentId in: query description: Unique identifier of the agent to which the batch run belongs. required: true schema: type: string example: agent_IqmljBh8eSEGAqKd responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/BatchResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/batch-runs status: 400 timestamp: 2026-05-05T10:06:43.890704 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/batch-runs status: 401 timestamp: 2026-05-05T10:06:43.890727 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/batch-runs status: 403 timestamp: 2026-05-05T10:06:43.890734 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/batch-runs status: 404 timestamp: 2026-05-05T10:06:43.890739 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/batch-runs status: 500 timestamp: 2026-05-05T10:06:43.890749 # Test Run APIs /v1/test-runs: get: tags: - Test Runs summary: List Test Runs description: "Returns a paginated list of test run results for the specified\ \ batch, sorted by most recently created first. Use page and size to navigate\ \ through results." operationId: listTestRuns parameters: - name: batchId in: query description: Unique identifier of the batch run whose test runs are to be listed. required: true schema: type: string example: batch_KidCyVw5gJN87n5S - name: agentId in: query description: Unique identifier of the agent to which the batch run belongs. required: true schema: type: string example: agent_IqmljBh8eSEGAqKd - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of test runs to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseTestCaseRunResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/test-runs status: 400 timestamp: 2026-05-05T10:06:43.766309 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/test-runs status: 401 timestamp: 2026-05-05T10:06:43.766340 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/test-runs status: 403 timestamp: 2026-05-05T10:06:43.766351 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/test-runs status: 404 timestamp: 2026-05-05T10:06:43.766358 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/test-runs status: 500 timestamp: 2026-05-05T10:06:43.766370 /v1/test-runs/{jobId}: get: tags: - Test Runs summary: Get Test Run description: "Retrieves the full details of a single test run by jobId, scoped\ \ to the specified batch and agent. Returns the test case name, execution\ \ status, expected and actual outcomes, and transcript details." operationId: getTestRun parameters: - name: jobId in: path description: The unique identifier of the simulation run to retrieve. required: true schema: type: string example: job_ksUu5yRHGTLLrLeM - name: batchId in: query description: The unique identifier of the batch run to which this simulation run belongs. required: true schema: type: string example: batch_KidCyVw5gJN87n5S - name: agentId in: query description: Unique identifier of the agent to which the batch run belongs. required: true schema: type: string example: agent_IqmljBh8eSEGAqKdq responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/TestCaseRunResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/test-runs status: 400 timestamp: 2026-05-05T10:06:43.782748 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/test-runs status: 401 timestamp: 2026-05-05T10:06:43.782781 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/test-runs status: 403 timestamp: 2026-05-05T10:06:43.782807 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/test-runs status: 404 timestamp: 2026-05-05T10:06:43.782819 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/test-runs status: 500 timestamp: 2026-05-05T10:06:43.782837 # QA Rule APIs /v1/qa-rules: get: tags: - QA Rules summary: List QA Rules description: "Returns a paginated list of all QA rules, sorted by most recently\ \ created first. Use page and size to navigate through results." operationId: listQARules parameters: - name: page in: query description: "The page number to retrieve, starting from 0." required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: The number of results to return per page. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseQARuleResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/qa-rules status: 400 timestamp: 2026-05-06T07:47:11.619222 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/qa-rules status: 401 timestamp: 2026-05-06T07:47:11.619242 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/qa-rules status: 403 timestamp: 2026-05-06T07:47:11.619253 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/qa-rules status: 404 timestamp: 2026-05-06T07:47:11.619259 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/qa-rules status: 500 timestamp: 2026-05-06T07:47:11.619269 post: tags: - QA Rules summary: Create QA Rule description: "Creates a new QA rule with the specified configuration. Define\ \ the rule's evaluation criteria and expected result. Returns the created\ \ QA rule, including its qaRuleId for subsequent get, update, delete, and issue-listing\ \ calls." operationId: createQARule requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateQARuleRequest' required: true responses: "201": description: OK content: application/json: schema: $ref: '#/components/schemas/QARuleResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/qa-rules status: 400 timestamp: 2026-05-06T07:47:11.209428 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/qa-rules status: 401 timestamp: 2026-05-06T07:47:11.209464 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/qa-rules status: 403 timestamp: 2026-05-06T07:47:11.209477 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/qa-rules status: 404 timestamp: 2026-05-06T07:47:11.209487 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/qa-rules status: 500 timestamp: 2026-05-06T07:47:11.209507 /v1/qa-rules/{qaRuleId}: get: tags: - QA Rules summary: Get QA Rule description: "Retrieves the full details of a single QA rule by qaRuleId. Returns\ \ the rule configuration including its evaluation criteria, expected value,\ \ and agents it will be applied to." operationId: getQARule parameters: - name: qaRuleId in: path description: The unique identifier of the QA rule to retrieve. required: true schema: type: string example: rule_YYdKgw1masomMfe8 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/QARuleResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/qa-rules status: 400 timestamp: 2026-05-06T07:47:11.623252 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/qa-rules status: 401 timestamp: 2026-05-06T07:47:11.623268 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/qa-rules status: 403 timestamp: 2026-05-06T07:47:11.623275 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/qa-rules status: 404 timestamp: 2026-05-06T07:47:11.623280 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/qa-rules status: 500 timestamp: 2026-05-06T07:47:11.623291 delete: tags: - QA Rules summary: Delete QA Rule description: Permanently deletes a QA rule by qaRuleId. Cannot be undone — the rule will no longer be evaluated against future interactions. Returns 204 No Content on success. operationId: deleteQARule parameters: - name: qaRuleId in: path description: The unique identifier of the QA Rule to delete. required: true schema: type: string example: rule_YYdKgw1masomMfe8 responses: "200": description: OK "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/qa-rules status: 400 timestamp: 2026-05-06T07:47:11.706485 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/qa-rules status: 401 timestamp: 2026-05-06T07:47:11.706503 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/qa-rules status: 403 timestamp: 2026-05-06T07:47:11.706519 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/qa-rules status: 404 timestamp: 2026-05-06T07:47:11.706524 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/qa-rules status: 500 timestamp: 2026-05-06T07:47:11.706532 patch: tags: - QA Rules summary: Update QA Rule description: Partially updates an existing QA rule by qaRuleId. Only fields provided in the request body are updated — omitted fields remain unchanged. Returns the updated QA rule record. operationId: patchUpdateQARule parameters: - name: qaRuleId in: path description: The unique identifier of the QA rule to update. required: true schema: type: string example: rule_YYdKgw1masomMfe8 requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateQARuleRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/QARuleResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/qa-rules status: 400 timestamp: 2026-05-06T07:47:11.486260 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/qa-rules status: 401 timestamp: 2026-05-06T07:47:11.486279 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/qa-rules status: 403 timestamp: 2026-05-06T07:47:11.486286 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/qa-rules status: 404 timestamp: 2026-05-06T07:47:11.486292 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/qa-rules status: 500 timestamp: 2026-05-06T07:47:11.486303 # QA Issue APIs /v1/qa-issues: get: tags: - QA Issues summary: List QA Issues description: "Returns a paginated list of QA issues for the specified QA rule,\ \ sorted by most recently created first. Use page and size to navigate through\ \ results." operationId: listQAIssues parameters: - name: qaRuleId in: query description: The unique identifier of the QA issue for which QA issues are to be listed. required: true schema: type: string example: issue_1fueLBh6mJxwLbe1 - name: page in: query description: "The page number to retrieve, starting from 0." required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: The number of results to return per page. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseQAIssueResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/qa-issues status: 400 timestamp: 2026-05-06T07:47:11.632661 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/qa-issues status: 401 timestamp: 2026-05-06T07:47:11.632684 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/qa-issues status: 403 timestamp: 2026-05-06T07:47:11.632691 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/qa-issues status: 404 timestamp: 2026-05-06T07:47:11.632697 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/qa-issues status: 500 timestamp: 2026-05-06T07:47:11.632707 /v1/qa-issues/{qaIssueId}: get: tags: - QA Issues summary: Get QA Issue description: "Retrieves the full details of a single QA issue by qaIssueId.\ \ Returns the issue record including its associated QA rule, status, reasons,\ \ and any metadata captured at detection time." operationId: getQAIssue parameters: - name: qaIssueId in: path description: The unique identifier of the QA issue to retrieve. required: true schema: type: string example: issue_1fueLBh6mJxwLbe1 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/QAIssueResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/qa-issues status: 400 timestamp: 2026-05-06T07:47:11.639026 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/qa-issues status: 401 timestamp: 2026-05-06T07:47:11.639047 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/qa-issues status: 403 timestamp: 2026-05-06T07:47:11.639054 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/qa-issues status: 404 timestamp: 2026-05-06T07:47:11.639066 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/qa-issues status: 500 timestamp: 2026-05-06T07:47:11.639077 # Knowledge Base APIs /v1/knowledge-bases: get: tags: - Knowledge bases summary: List knowledge bases description: "Returns a paginated list of knowledge bases for the account, sorted\ \ by most recently updated. Each item includes its sources and timestamps.\ \ Use page and size for pagination." operationId: list parameters: - name: page in: query description: Zero-based page number to retrieve. Use 0 for the first page. Must be 0 or greater. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Number of knowledge bases to return per page. Must be 1 or greater. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: Paginated knowledge bases for this account (may be an empty page). content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseKnowledgeBaseResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/knowledge-bases status: 400 timestamp: 2026-05-14T14:27:22.325319 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/knowledge-bases status: 401 timestamp: 2026-05-14T14:27:22.325333 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/knowledge-bases status: 403 timestamp: 2026-05-14T14:27:22.325340 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/knowledge-bases status: 404 timestamp: 2026-05-14T14:27:22.325346 "413": description: Payload Too Large content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Payload Too Large message: An uploaded file exceeds the per-file size limit (25 MB). path: /v1/knowledge-bases status: 413 timestamp: 2026-05-14T14:27:22.325350 "415": description: Unsupported Media Type content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unsupported Media Type message: "Uploaded file type is not supported. Allowed: PDF, TXT,\ \ HTML, Markdown, DOCX." path: /v1/knowledge-bases status: 415 timestamp: 2026-05-14T14:27:22.325353 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Something went wrong on the server path: /v1/knowledge-bases status: 500 timestamp: 2026-05-14T14:27:22.325356 post: tags: - Knowledge bases summary: Create knowledge base description: "Creates a knowledge base by providing a name, optional text snippets,\ \ URLs, and file attachments. Sources are processed in order: text, URLs,\ \ then files. Supported file types include PDF, TXT, HTML, Markdown, and DOCX.\ \ Maximum file size is 25 MB." operationId: createMultipart parameters: - name: knowledge_base_name in: query description: Name of the new knowledge base. Names do not need to be unique. required: true schema: type: string example: Sample KB - name: knowledge_base_texts in: query description: "Optional. Send as one form field whose value is a JSON array\ \ string. Example: `knowledge_base_texts=[\"Hello\",{\"title\":\"Q\",\"\ text\":\"A\"}]`. Plain strings become text sources; objects may use `title`\ \ and/or `text`." required: false schema: type: string example: - Hello - title: Q text: A - name: knowledge_base_urls in: query description: "Optional. Send as one form field whose value is a JSON array\ \ of URL strings (not native repeated fields). Example: `knowledge_base_urls=[\"\ https://example.com/docs\"]`. Each entry must be a URL string." required: false schema: type: string example: - https://example.com/docs requestBody: content: multipart/form-data: schema: type: object properties: knowledge_base_files: type: array description: "Optional. Attach one or more files using the same\ \ field name repeated. Allowed file types: PDF, TXT, HTML, Markdown,\ \ DOCX. Max file size - 25 MB" items: type: string format: binary responses: "201": description: Created. content: application/json: schema: $ref: '#/components/schemas/KnowledgeBaseResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/knowledge-bases status: 400 timestamp: 2026-05-14T14:27:21.959482 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/knowledge-bases status: 401 timestamp: 2026-05-14T14:27:21.959505 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/knowledge-bases status: 403 timestamp: 2026-05-14T14:27:21.959511 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/knowledge-bases status: 404 timestamp: 2026-05-14T14:27:21.959515 "413": description: Payload Too Large content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Payload Too Large message: An uploaded file exceeds the per-file size limit (25 MB). path: /v1/knowledge-bases status: 413 timestamp: 2026-05-14T14:27:21.959519 "415": description: Unsupported Media Type content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unsupported Media Type message: "Uploaded file type is not supported. Allowed: PDF, TXT,\ \ HTML, Markdown, DOCX." path: /v1/knowledge-bases status: 415 timestamp: 2026-05-14T14:27:21.959524 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Something went wrong on the server path: /v1/knowledge-bases status: 500 timestamp: 2026-05-14T14:27:21.959543 /v1/knowledge-bases/{kbId}: get: tags: - Knowledge bases summary: Get knowledge base description: Retrieves a single knowledge base along with its associated sources and timestamps. operationId: get parameters: - name: kbId in: path description: Knowledge base id from a create or list response. required: true schema: type: string example: kb_6sbr3tbMX757M0VD responses: "200": description: The knowledge base. content: application/json: schema: $ref: '#/components/schemas/KnowledgeBaseResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/knowledge-bases status: 400 timestamp: 2026-05-14T14:27:22.328067 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/knowledge-bases status: 401 timestamp: 2026-05-14T14:27:22.328080 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/knowledge-bases status: 403 timestamp: 2026-05-14T14:27:22.328087 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/knowledge-bases status: 404 timestamp: 2026-05-14T14:27:22.328091 "413": description: Payload Too Large content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Payload Too Large message: An uploaded file exceeds the per-file size limit (25 MB). path: /v1/knowledge-bases status: 413 timestamp: 2026-05-14T14:27:22.328094 "415": description: Unsupported Media Type content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unsupported Media Type message: "Uploaded file type is not supported. Allowed: PDF, TXT,\ \ HTML, Markdown, DOCX." path: /v1/knowledge-bases status: 415 timestamp: 2026-05-14T14:27:22.328098 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Something went wrong on the server path: /v1/knowledge-bases status: 500 timestamp: 2026-05-14T14:27:22.328101 delete: tags: - Knowledge bases summary: Delete knowledge base description: Deletes a knowledge base along with all its associated sources. This action is irreversible. operationId: delete parameters: - name: kbId in: path description: The kbId of the knowledge base to permanently delete. This action cannot be undone. required: true schema: type: string example: kb_6sbr3tbMX757M0VD responses: "204": description: Deleted. "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/knowledge-bases status: 400 timestamp: 2026-05-14T14:27:22.389499 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/knowledge-bases status: 401 timestamp: 2026-05-14T14:27:22.389518 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/knowledge-bases status: 403 timestamp: 2026-05-14T14:27:22.389522 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/knowledge-bases status: 404 timestamp: 2026-05-14T14:27:22.389525 "413": description: Payload Too Large content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Payload Too Large message: An uploaded file exceeds the per-file size limit (25 MB). path: /v1/knowledge-bases status: 413 timestamp: 2026-05-14T14:27:22.389528 "415": description: Unsupported Media Type content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unsupported Media Type message: "Uploaded file type is not supported. Allowed: PDF, TXT,\ \ HTML, Markdown, DOCX." path: /v1/knowledge-bases status: 415 timestamp: 2026-05-14T14:27:22.389531 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Something went wrong on the server path: /v1/knowledge-bases status: 500 timestamp: 2026-05-14T14:27:22.389534 patch: tags: - Knowledge bases summary: Update knowledge base description: "Updates a knowledge base by adding new sources and/or modifying\ \ its name. Supported file types include PDF, TXT, HTML, Markdown, and DOCX.\ \ Maximum file size is 25 MB." operationId: updateMultipart parameters: - name: kbId in: path description: Knowledge base id to change. required: true schema: type: string example: kb_6sbr3tbMX757M0VD - name: knowledge_base_name in: query description: "New name, if you want to rename. Names do not need to be unique." required: false schema: type: string example: Sample KB v2 - name: knowledge_base_texts in: query description: "Optional new text sources. Send as one form field whose value\ \ is a JSON array string. Example: `knowledge_base_texts=[\"Hello\",{\"\ title\":\"Q\",\"text\":\"A\"}]`." required: false schema: type: string example: - Updated note - name: knowledge_base_urls in: query description: "Optional new URL sources. Send as one form field whose value\ \ is a JSON array of URL strings (not native repeated fields). Example:\ \ `knowledge_base_urls=[\"https://example.com/docs\"]`." required: false schema: type: string example: - https://example.com/new requestBody: content: multipart/form-data: schema: type: object properties: knowledge_base_files: type: array description: "Optional files, field may be repeated. Allowed file\ \ types: PDF, TXT, HTML, Markdown, DOCX. Max file size - 25 MB" items: type: string format: binary responses: "200": description: Updated knowledge base. content: application/json: schema: $ref: '#/components/schemas/KnowledgeBaseResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/knowledge-bases status: 400 timestamp: 2026-05-14T14:27:22.199360 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/knowledge-bases status: 401 timestamp: 2026-05-14T14:27:22.199377 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/knowledge-bases status: 403 timestamp: 2026-05-14T14:27:22.199381 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/knowledge-bases status: 404 timestamp: 2026-05-14T14:27:22.199384 "413": description: Payload Too Large content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Payload Too Large message: An uploaded file exceeds the per-file size limit (25 MB). path: /v1/knowledge-bases status: 413 timestamp: 2026-05-14T14:27:22.199388 "415": description: Unsupported Media Type content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unsupported Media Type message: "Uploaded file type is not supported. Allowed: PDF, TXT,\ \ HTML, Markdown, DOCX." path: /v1/knowledge-bases status: 415 timestamp: 2026-05-14T14:27:22.199392 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Something went wrong on the server path: /v1/knowledge-bases status: 500 timestamp: 2026-05-14T14:27:22.199395 /v1/knowledge-bases/{kbId}/documents/{documentId}: delete: tags: - Knowledge bases summary: Delete document description: Deletes a specific source from a knowledge base. Other sources remain unaffected. operationId: deleteDocument parameters: - name: kbId in: path description: The kbId of the knowledge base containing the document to remove. required: true schema: type: string example: kb_6sbr3tbMX757M0VD - name: documentId in: path description: Source id from the knowledge base details (starts with `doc_`). required: true schema: type: string example: doc_a1b2c3d4e5f67890 responses: "204": description: Removed. "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/knowledge-bases status: 400 timestamp: 2026-05-14T14:27:22.390670 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/knowledge-bases status: 401 timestamp: 2026-05-14T14:27:22.390680 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/knowledge-bases status: 403 timestamp: 2026-05-14T14:27:22.390684 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/knowledge-bases status: 404 timestamp: 2026-05-14T14:27:22.390687 "413": description: Payload Too Large content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Payload Too Large message: An uploaded file exceeds the per-file size limit (25 MB). path: /v1/knowledge-bases status: 413 timestamp: 2026-05-14T14:27:22.390690 "415": description: Unsupported Media Type content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unsupported Media Type message: "Uploaded file type is not supported. Allowed: PDF, TXT,\ \ HTML, Markdown, DOCX." path: /v1/knowledge-bases status: 415 timestamp: 2026-05-14T14:27:22.390693 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Something went wrong on the server path: /v1/knowledge-bases status: 500 timestamp: 2026-05-14T14:27:22.390696 # Mock Tool Data APIs /v1/mock-tool-data: get: tags: - Mock Tool Data summary: List Mock Tool Data description: "Returns a paginated list of mock tool data records, optionally\ \ filtered by agentId and toolId. Sorted by most recently created first." operationId: listMockToolData parameters: - name: agentId in: query description: "Optional agent identifier. When supplied, only mocks for this\ \ agent are returned." required: false schema: type: string example: agent_D5D0p7TUs66TTAEAx - name: toolId in: query description: Tool for which mock tool data records are to be displayed. required: false schema: type: string example: tool_X9pLm2Wq8Rt3 - name: page in: query description: Zero-based page number. Defaults to 0. required: false schema: type: integer format: int32 default: 0 example: 0 - name: size in: query description: Page size. Defaults to 10. required: false schema: type: integer format: int32 default: 10 example: 10 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PaginatedResponseMockToolDataResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/mock-tool-data status: 400 timestamp: 2026-10-14T11:41:39.122264 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/mock-tool-data status: 401 timestamp: 2026-10-14T11:41:39.122278 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/mock-tool-data status: 403 timestamp: 2026-10-14T11:41:39.122284 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/mock-tool-data status: 404 timestamp: 2026-10-14T11:41:39.122288 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/mock-tool-data status: 500 timestamp: 2026-10-14T11:41:39.122292 post: tags: - Mock Tool Data summary: Create Mock Tool Data description: Creates a named mock tool data in the tenant mock library. Use this for manual mock tool data creation or after capturing a live tool execute. Returns the created mock including its mockToolDataId. operationId: createMockToolData requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateMockToolDataRequest' required: true responses: "201": description: Created content: application/json: schema: $ref: '#/components/schemas/MockToolDataResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/mock-tool-data status: 400 timestamp: 2026-10-14T11:41:38.503640 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/mock-tool-data status: 401 timestamp: 2026-10-14T11:41:38.503666 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/mock-tool-data status: 403 timestamp: 2026-10-14T11:41:38.503676 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/mock-tool-data status: 404 timestamp: 2026-10-14T11:41:38.503685 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/mock-tool-data status: 500 timestamp: 2026-10-14T11:41:38.503693 /v1/mock-tool-data/{mockToolDataId}: get: tags: - Mock Tool Data summary: Get Mock Tool Data description: "Retrieves a single mock tool data record by mockToolDataId. agentId\ \ is optional; when supplied, returns mocks that belong to that agent." operationId: getMockToolData parameters: - name: mockToolDataId in: path description: Unique identifier of the mock tool data record. required: true schema: type: string example: mock_dpKjqjKnY3z6gABF - name: agentId in: query description: "Optional agent identifier. When supplied, returns mocks that\ \ belong to the agent." required: false schema: type: string example: agent_D5D0p7TUs66TTAEAx responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/MockToolDataResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/mock-tool-data status: 400 timestamp: 2026-10-14T11:41:39.125142 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/mock-tool-data status: 401 timestamp: 2026-10-14T11:41:39.125156 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/mock-tool-data status: 403 timestamp: 2026-10-14T11:41:39.125162 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/mock-tool-data status: 404 timestamp: 2026-10-14T11:41:39.125167 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/mock-tool-data status: 500 timestamp: 2026-10-14T11:41:39.125171 delete: tags: - Mock Tool Data summary: Delete Mock Tool Data description: 'Deletes a mock tool data record for the specified agent. Fails if any active test case still references this mock via mockToolData. ' operationId: deleteMockToolData parameters: - name: mockToolDataId in: path description: Unique identifier of the mock tool data record. required: true schema: type: string example: mock_dpKjqjKnY3z6gABF - name: agentId in: query description: Unique identifier of the agent this mock belongs to. required: true schema: type: string example: agent_D5D0p7TUs66TTAEAx responses: "200": description: OK "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/mock-tool-data status: 400 timestamp: 2026-10-14T11:41:39.261817 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/mock-tool-data status: 401 timestamp: 2026-10-14T11:41:39.261828 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/mock-tool-data status: 403 timestamp: 2026-10-14T11:41:39.261833 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/mock-tool-data status: 404 timestamp: 2026-10-14T11:41:39.261836 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/mock-tool-data status: 500 timestamp: 2026-10-14T11:41:39.261840 "409": description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Conflict message: Mock is still referenced by one or more test cases path: "/v1/mock-tool-data/{mockToolDataId}" status: 409 timestamp: 2026-10-14T11:41:39.261844 patch: tags: - Mock Tool Data summary: Update Mock Tool Data description: Partially updates a mock tool data record for the specified agent. agentId is required. Only other provided fields are changed. operationId: updateMockToolData parameters: - name: mockToolDataId in: path description: Unique identifier of the mock tool data record. required: true schema: type: string example: mock_dpKjqjKnY3z6gABF requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateMockToolDataRequest' required: true responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/MockToolDataResponse' "400": description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Bad Request message: Invalid request parameters path: /v1/mock-tool-data status: 400 timestamp: 2026-10-14T11:41:38.896809 "401": description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Unauthorized message: X-API-Key is missing or invalid path: /v1/mock-tool-data status: 401 timestamp: 2026-10-14T11:41:38.896826 "403": description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Forbidden message: Access denied for this resource path: /v1/mock-tool-data status: 403 timestamp: 2026-10-14T11:41:38.896833 "404": description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Not Found message: The requested resource was not found path: /v1/mock-tool-data status: 404 timestamp: 2026-10-14T11:41:38.896838 "500": description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' examples: default: value: error: Internal Server Error message: Unexpected server error path: /v1/mock-tool-data status: 500 timestamp: 2026-10-14T11:41:38.896842 components: schemas: # Calls APIs Schemas CreateCallRequest: required: - fromPhoneNumber - toPhoneNumber type: object properties: fromPhoneNumber: pattern: "^\\+[1-9][0-9]{6,14}$" type: string description: "Caller's phone number in +E.164 format (e.g., +14155552671).\ \ Must be a number provisioned in SigmaMind or configured via SIP trunking\ \ that is enabled for outbound calls. This number appears as the caller\ \ ID on the recipient's device." example: "+14155552671" toPhoneNumber: pattern: "^\\+[1-9][0-9]{6,14}$" type: string description: "Destination phone number to dial, in +E.164 format (e.g.,\ \ +14155552671). Must be a valid number capable of receiving calls. Include\ \ the country code — local-format numbers without a leading '+' are rejected." example: "+14155552671" agentId: maxLength: 64 minLength: 0 type: string description: "Unique identifier of the agent that will handle this call.\ \ The agent controls the conversation flow, prompts, and any tools invoked\ \ during the call. If omitted, the default agent configured for the caller's\ \ phone number is used." example: agent_D5D0p7TUs66TTAEAx dynamicVariables: type: object description: "Key-value pairs used to personalise the agent's behaviour\ \ for this specific call. Keys must match the variable names defined in\ \ the agent's configuration (e.g., 'customer_name', 'account_id'). These\ \ values are injected into the agent's prompts and tools at call start.\ \ Leave empty if the agent requires no personalisation." additionalProperties: oneOf: - type: string - type: number - type: boolean - type: object - type: array example: customer_name: Michael account_id: ACC-001 description: "Request body to initiate a single outbound call. Requires a SigmaMind-provisioned\ \ caller number, a destination number, and the agent that will handle the\ \ call. Dynamic variables allow the agent to personalise the conversation\ \ at runtime." CallResponse: type: object properties: callId: type: string description: "Unique identifier for this call. Use this value as callId\ \ when retrieving, updating, or referencing this call in subsequent API\ \ calls." example: call_AuUKK371Spr5nHJS callType: type: string description: Direction and channel of the call. 'inbound' means the call was received by SigmaMind from an external caller. 'outbound' means SigmaMind dialled the destination number. 'web' means the call originated from a browser-based session. example: outbound enum: - inbound - outbound - web - chat phoneNumber: $ref: '#/components/schemas/PhoneNumberResponse' campaign: $ref: '#/components/schemas/CampaignResponse' status: type: string description: Current lifecycle state of the call. 'scheduled' means the call is queued but dialling has not started. 'in_progress' means the call is currently active. 'ended' means the call completed normally. 'not_connected' means the call was attempted but the recipient did not answer or connect. 'error' means the system encountered a failure while trying to place or manage the call. example: ended enum: - scheduled - in_progress - ended - not_connected - error transcript: type: string description: transcript of the conversation in chat startTime: type: string description: "UTC timestamp when the call was connected and the active session\ \ began, in ISO 8601 format. Null if the call never reached in_progress\ \ state." format: date-time example: 2024-04-20T10:00:00Z endTime: type: string description: "UTC timestamp when the call session ended, in ISO 8601 format.\ \ Null if the call is still in progress or was never connected." format: date-time example: 2024-04-20T10:02:00Z duration: type: integer description: Total duration of the connected call session in seconds. Measured from startTime to endTime. Null if the call was never connected. format: int32 example: 120 terminationReason: type: string description: Reason the call session ended. 'silence_timed_out' — call ended due to configured silence timeout. 'agent_ended_call' — the AI agent closed the session. 'user_ended_call' — the recipient hung up the call. 'voicemail_detected' — voicemail was detected during the call. 'ivr_detected' — IVR system was detected during the call. 'agent_transferred_call' — the AI agent transferred the call. 'max_call_duration_exceeded' — maximum call duration limit was exceeded. 'dial_telephony_permission_denied' — outbound dialing permission was denied by telephony provider. 'dial_invalid_destination' — destination number was invalid. 'dial_no_answer' — the call rang but was not answered. 'dial_user_declined' — recipient declined the incoming call. 'dial_busy' — the destination number was busy. 'dial_failed' — outbound dialing failed due to SIP or telephony error. 'error_credit_limit_reached' — insufficient credit balance. 'error_llm' — language model failed to generate a response. 'error_tts' — text-to-speech service error occurred. 'error_asr' — speech recognition service error occurred. 'error_sigmamind' — internal SigmaMind processing error occurred. 'error_telephony' — telephony provider or connection error occurred. 'error_unknown' — unknown internal error occurred. Null if the call has not yet ended. example: user_ended_call enum: - silence_timed_out - agent_ended_call - user_ended_call - voicemail_detected - ivr_detected - agent_transferred_call - max_call_duration_exceeded - dial_telephony_permission_denied - dial_invalid_destination - dial_no_answer - dial_user_declined - dial_busy - dial_failed - error_credit_limit_reached - error_llm - error_tts - error_asr - error_sigmamind - error_telephony - error_unknown createdAt: type: string description: "UTC timestamp when this call record was created in the system,\ \ in ISO 8601 format. For outbound calls this is typically when the call\ \ was scheduled or triggered." format: date-time example: 2024-04-20T09:59:50Z updatedAt: type: string description: "UTC timestamp when this call record was last updated, in ISO\ \ 8601 format. Updates occur when the call status changes, the session\ \ ends, or metadata is modified." format: date-time example: 2024-04-20T10:02:05Z dynamicVariables: $ref: '#/components/schemas/JsonNode' recordingUrl: type: string description: URL of the call recording audio file. Available after the call ends and recording processing is complete. Null if recording is not enabled for this call or if the call did not connect. example: https://livekitmedia.blob.core.windows.net/recording-container-prod/room-ST_abc123/recording.mp3 agent: $ref: '#/components/schemas/AgentResponse' description: "Full details of a single call record. Includes call identity,\ \ direction, status, timing, the agent that handled it, and the campaign it\ \ belongs to if applicable." PaginatedResponseCallResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/CallResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # Chat APIs Schemas CreateChatRequest: required: - agentId - input type: object properties: agentId: maxLength: 64 minLength: 1 type: string description: The unique identifier of the Agent assigned to handle the chat completion. example: agent_D5D0p7TUs66TTAEAx input: maxLength: 20480 minLength: 1 type: string description: Input message from the customer or conversation history. example: Where is my order? dynamicVariables: type: object description: "Dynamic key-value pairs required by the selected Agent for\ \ personalisation (e.g. customer name, account details)." example: customer_name: Michael additionalProperties: oneOf: - type: string - type: number - type: boolean - type: object - type: array previousChatId: maxLength: 128 minLength: 0 type: string description: Unique ID of a previous chat session to use as context for this chat. example: chat_D5D0p7TUs66TTAEAx CreateChatCompletionRequest: required: - chatId - input type: object properties: chatId: maxLength: 128 minLength: 1 type: string description: The unique identifier of the chat session in a specific agent. example: chat_nZ9hHYAANJbhLwZv input: maxLength: 20480 minLength: 1 type: string description: Input message from the customer. example: Where is my order? UpdateChatRequest: type: object properties: agentId: maxLength: 64 minLength: 0 type: string description: The unique identifier of the Agent assigned to handle the chat completion. example: agent_D5D0p7TUs66TTAEAx dynamicVariables: type: object description: "Dynamic key-value pairs required by the selected Agent for\ \ personalisation (e.g. customer name, account details)." example: customer_name: Michael additionalProperties: oneOf: - type: string - type: number - type: boolean - type: object - type: array ChatCompletionResponse: type: object properties: chatId: type: string description: Unique identity for a chat example: chat_d17T6uReChpyfFeP createdAt: type: string description: The timestamp when the call record was created. format: date-time example: 2021-04-20T10:00:00Z status: type: string description: Status of the chat example: ended enum: - in_progress - ended - error response: type: array description: Agent response of the last user message example: - id: item_G9YdhDqua0EngI1G role: assistant type: message content: - "Hello! My name is Grace, and I'm calling on behalf of SigmaMind AI.\ \ Am I speaking with Michael?" items: $ref: '#/components/schemas/ChatMessage' agent: $ref: '#/components/schemas/AgentResponse' ChatMessage: type: object properties: id: type: string description: Unique identity for a chat message example: item_d17T6uReChpyfFeP role: type: string description: Role of the chat message example: user enum: - user - assistant type: type: string description: Type of the chat message example: message enum: - message content: type: array description: Chat message content example: "Hello! My name is Grace, and I'm calling on behalf of SigmaMind\ \ AI. Am I speaking with Michael?" items: type: string description: Chat message content example: "Hello! My name is Grace, and I'm calling on behalf of SigmaMind\ \ AI. Am I speaking with Michael?" description: Agent response of the last user message example: - id: item_G9YdhDqua0EngI1G role: assistant type: message content: - "Hello! My name is Grace, and I'm calling on behalf of SigmaMind AI. Am\ \ I speaking with Michael?" ChatResponse: type: object properties: chatId: type: string description: Unique identity for a chat example: chat-d17T6uReChpyfFeP agent: $ref: '#/components/schemas/AgentResponse' createdAt: type: string description: The timestamp when the call record was created. format: date-time example: 2021-04-20T10:00:00Z status: type: string description: Status of chat example: ended transcript: type: string description: transcript of the conversation in chat response: type: array description: Agent response of the last user message example: - id: item_G9YdhDqua0EngI1G role: assistant type: message content: - "Hello! My name is Grace, and I'm calling on behalf of SigmaMind AI.\ \ Am I speaking with Michael?" items: $ref: '#/components/schemas/ChatMessage' messages: type: array description: Agent response of the last user message example: - id: item_G9YdhDqua0EngI1G role: assistant type: message content: - "Hello! My name is Grace, and I'm calling on behalf of SigmaMind AI.\ \ Am I speaking with Michael?" items: $ref: '#/components/schemas/ChatMessage' dynamicVariables: $ref: '#/components/schemas/JsonNode' PaginatedResponseChatResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/ChatResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # Phone Number APIs Schemas CreatePhoneNumberRequest_Telephony: type: object properties: friendlyName: maxLength: 128 minLength: 0 type: string description: "Human-readable label for this phone number. Used to identify\ \ it in listings and dashboards. If omitted, the number itself is used\ \ as the display name." example: Support Line - US countryCode: pattern: "^[A-Z]{2}$" type: string description: "ISO 3166-1 alpha-2 country code that determines which country\ \ the number is purchased from. Required when phoneNumber is not provided\ \ — the system selects an available number in this country. Ignored when\ \ phoneNumber is explicitly specified. Must be exactly two uppercase letters\ \ (e.g., 'US', 'IN', 'GB')." example: US areaCode: maximum: 99999 minimum: 100 type: integer description: "Preferred area or region code used to narrow down number selection\ \ within the specified country. Optional — only considered when countryCode\ \ is provided and phoneNumber is omitted. If no number is available in\ \ this area code, the system selects the nearest available match." format: int32 example: 415 phoneNumber: pattern: "^\\+[1-9][0-9]{6,14}$" type: string description: "Specific phone number to purchase, in +E.164 format (e.g.,\ \ +14155552671). When provided, the system attempts to purchase exactly\ \ this number. Either this field or countryCode must be supplied — both\ \ cannot be omitted. If omitted, the system auto-selects an available\ \ number based on countryCode and areaCode." example: "+14155552671" inboundAgentId: maxLength: 64 minLength: 0 type: string description: "Unique identifier of the agent that will handle inbound calls\ \ received on this number. When a call arrives at this number, it is routed\ \ to this agent automatically. If omitted, inbound calls will not be handled\ \ by an agent until one is assigned." example: awTw7UKhOsLGiDbt outboundAgentId: maxLength: 64 minLength: 0 type: string description: "Unique identifier of the agent that will handle outbound calls\ \ made from this number. When this number is used as the caller ID in\ \ an outbound call, this agent manages the conversation. If omitted, the\ \ agent must be specified explicitly at call creation time." example: awTw7UKhOsLGiDbt outboundPhoneNumber: pattern: "^\\+[1-9][0-9]{6,14}$" type: string description: "Default destination number dialled during test calls initiated\ \ from this phone number, in +E.164 format. Used to verify the number\ \ is working correctly without targeting a real contact. Must be a valid\ \ number capable of receiving calls. If omitted, test calls cannot be\ \ placed until this is configured." example: "+14155552671" description: "Request body to purchase and provision a new phone number through\ \ SigmaMind. Either phoneNumber or countryCode must be provided. Supply phoneNumber\ \ to purchase a specific number, or supply countryCode (with optional areaCode)\ \ to let the system auto-select an available number in that region." ImportPhoneNumberRequest_Byo: type: object properties: friendlyName: maxLength: 128 minLength: 0 type: string description: "Human-readable label for this phone number. Used to identify\ \ it in listings and dashboards. If omitted, the number itself is used\ \ as the display name." example: BYO - Main Office Line phoneNumber: pattern: "^\\+[1-9][0-9]{6,14}$" type: string description: "The phone number being imported, in +E.164 format (e.g., +14155552671).\ \ Must be a number you own and have configured on your external SIP trunk.\ \ This number will be registered in SigmaMind and used as the caller ID\ \ for outbound calls and the destination for inbound calls routed through\ \ your trunk." example: "+14155552671" inboundAgentId: maxLength: 64 minLength: 0 type: string description: "Unique identifier of the agent that will handle inbound calls\ \ received on this number. When a call arrives at this number via the\ \ SIP trunk, it is routed to this agent automatically. If omitted, inbound\ \ calls will not be handled by an agent until one is assigned." example: awTw7UKhOsLGiDbt outboundAgentId: maxLength: 64 minLength: 0 type: string description: "Unique identifier of the agent that will handle outbound calls\ \ made from this number. When this number is used as the caller ID in\ \ an outbound call, this agent manages the conversation. If omitted, the\ \ agent must be specified explicitly at call creation time." example: awTw7UKhOsLGiDbt trunkUsername: maxLength: 128 minLength: 0 type: string description: Username credential for authenticating outbound calls on your SIP trunk. Must match the trunk username configured in your telecom provider's account. Required for outbound call routing through the trunk. example: my_trunk_user trunkPassword: maxLength: 128 minLength: 0 type: string description: Password credential for authenticating outbound calls on your SIP trunk. Must match the trunk password configured in your telecom provider's account. Required for outbound call routing through the trunk. Stored securely and never returned in API responses. example: tr!nkP@ssword terminationSipURI: maxLength: 253 minLength: 0 type: string description: "SIP URI of the termination endpoint provided by your telecom\ \ provider. SigmaMind sends outbound calls to this address to route them\ \ through your trunk. Obtain this value from your provider's SIP trunking\ \ configuration (e.g., 'sip.telnyx.com', 'sip.twilio.com'). Required for\ \ outbound call delivery." example: sip.telnyx.com outboundPhoneNumber: pattern: "^\\+[1-9][0-9]{6,14}$" type: string description: "Default destination number dialled during test calls initiated\ \ from this phone number, in +E.164 format. Used to verify the SIP trunk\ \ is connected and routing calls correctly. Must be a valid number capable\ \ of receiving calls. If omitted, test calls cannot be placed until this\ \ is configured." example: "+14155552671" description: Request body to import an existing phone number you own into SigmaMind via SIP trunking (BYO — Bring Your Own number). Use this when the number is already provisioned with an external telecom provider and you want SigmaMind to route calls through it using your own SIP trunk credentials. The number is not purchased — it remains with your provider. PhoneNumberResponse: type: object properties: sipPhoneNumber: type: string description: The caller’s phone number in +E.164 format. This number must be obtained from SigmaMind or configured using SIP trunking with SigmaMind. example: "+14155552671" provider: type: string description: The service provider associated with the phone number. example: twilio enum: - twilio - telnyx - byo inboundAgentId: type: string description: Default agent ID assigned to handle inbound calls for this phone number. example: agent_D5D0p7TUs66TTAEAx outboundAgentId: type: string description: Default agent ID assigned to handle outbound calls for this phone number. example: agent_D5D0p7TUs66TTAEAx outboundPhoneNumber: type: string description: "The default outbound phone number of the callee, represented\ \ in +E.164 format" example: "+14155552671" active: type: boolean description: Indicates whether the phone number is currently active and available for use. example: true terminationSipURI: type: string description: "The SIP URI of the phone number, provided by the service provider\ \ for call termination." example: sip.telnyx.com friendlyName: type: string description: A user-friendly display name assigned to this phone number. example: Support Line - US description: Caller phone number used to dial contacts in this campaign. This number appears as the caller ID on recipients' devices. PhoneNumberResponse_Telephony: type: object properties: sipPhoneNumber: type: string description: The caller’s phone number in +E.164 format. This number must be obtained from SigmaMind or configured using SIP trunking with SigmaMind. example: "+14155552671" provider: type: string description: The service provider associated with the phone number. example: twilio enum: - twilio - telnyx - byo inboundAgentId: type: string description: Default agent ID assigned to handle inbound calls for this phone number. example: agent_D5D0p7TUs66TTAEAx outboundAgentId: type: string description: Default agent ID assigned to handle outbound calls for this phone number. example: agent_D5D0p7TUs66TTAEAx outboundPhoneNumber: type: string description: "The default outbound phone number of the callee, represented\ \ in +E.164 format" example: "+14155552671" active: type: boolean description: Indicates whether the phone number is currently active and available for use. example: true friendlyName: type: string description: A user-friendly display name assigned to this phone number. example: Support Line - US PhoneNumberResponse_Byo: type: object properties: sipPhoneNumber: type: string description: The caller’s phone number in +E.164 format. This number must be obtained from SigmaMind or configured using SIP trunking with SigmaMind. example: "+14155552671" inboundAgentId: type: string description: Default agent ID assigned to handle inbound calls for this phone number. example: agent_D5D0p7TUs66TTAEAx outboundAgentId: type: string description: Default agent ID assigned to handle outbound calls for this phone number. example: agent_D5D0p7TUs66TTAEAx outboundPhoneNumber: type: string description: "The default outbound phone number of the callee, represented\ \ in +E.164 format" example: "+14155552671" active: type: boolean description: Indicates whether the phone number is currently active and available for use. example: true terminationSipURI: type: string description: "The SIP URI of the phone number, provided by the service provider\ \ for call termination." example: sip.telnyx.com friendlyName: type: string description: A user-friendly display name assigned to this phone number. example: Support Line - US UpdatePhoneNumberRequest: type: object properties: friendlyName: maxLength: 128 minLength: 0 type: string description: Updated human-readable label for this phone number. Used to identify it in listings and dashboards. Omit to leave the existing label unchanged. example: Support Line - US inboundAgentId: maxLength: 64 minLength: 0 type: string description: Updated agent ID for handling inbound calls received on this number. Replaces the currently assigned inbound agent. All inbound calls arriving after this update will be routed to the new agent. Pass null to remove the inbound agent assignment. Omit to leave the existing assignment unchanged. example: awTw7UKhOsLGiDbt outboundAgentId: maxLength: 64 minLength: 0 type: string description: Updated agent ID for handling outbound calls made from this number. Replaces the currently assigned outbound agent. All outbound calls placed after this update will use the new agent. Pass null to remove the outbound agent assignment. Omit to leave the existing assignment unchanged. example: awTw7UKhOsLGiDbt terminationSipUri: maxLength: 253 minLength: 0 type: string description: Updated SIP URI of the termination endpoint used to route outbound calls through the SIP trunk. Applicable only for BYO numbers imported via SIP trunking — has no effect on SigmaMind-provisioned numbers. Obtain this value from your telecom provider's SIP trunking configuration. Omit to leave the existing SIP URI unchanged. example: sip.telnyx.com trunkUsername: maxLength: 128 minLength: 0 type: string description: Updated username for authenticating outbound calls on the SIP trunk. Applicable only for BYO numbers — must match the trunk username in your provider's account. Omit to leave the existing username unchanged. example: my_trunk_user trunkPassword: maxLength: 128 minLength: 0 type: string description: Updated password for authenticating outbound calls on the SIP trunk. Applicable only for BYO numbers — must match the trunk password in your provider's account. Stored securely and never returned in API responses. Omit to leave the existing password unchanged. example: tr!nkP@ssword outboundPhoneNumber: pattern: "^\\+[1-9][0-9]{6,14}$" type: string description: "Updated default destination number for test calls placed from\ \ this number, in +E.164 format. Used to verify the number and trunk configuration\ \ are working correctly. Must be a valid number capable of receiving calls.\ \ Omit to leave the existing test number unchanged." example: "+14155552671" description: Request body to partially update a phone number record. Only fields included in the request are updated — omitted fields remain unchanged. Applies to both SigmaMind-provisioned numbers and BYO numbers imported via SIP trunking. PaginatedResponsePhoneNumberResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/PhoneNumberResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # Agent APIs Schemas CreateAgentRequest: required: - instructions type: object properties: agentName: maxLength: 128 minLength: 0 type: string description: Human-readable name of the agent used to identify it in the dashboard and APIs. example: Auralis instructions: type: string description: "Core system prompt that defines the agent’s behavior, personality,\ \ tone, response style, goals, and task handling logic. These instructions\ \ guide how the agent interacts with users and responds during conversations." example: You are a helpful customer support assistant. Answer concisely and professionally. welcomeMessageType: type: string description: "Determines how the agent’s welcome message is generated. Use\ \ 'static' to send a fixed predefined message, or 'prompt' to dynamically\ \ generate the welcome message using AI instructions." example: static enum: - static - prompt welcomeMessage: type: string description: "The content of the welcome message. If 'welcomeMessageType'\ \ is 'static', this contains the exact message shown to the user. If it\ \ is 'prompt', this contains the prompt used to generate the welcome message\ \ dynamically." example: Welcome to our service! How can I assist you today? agentSettings: $ref: '#/components/schemas/CreateAgentSettingsRequest' tools: type: array items: $ref: '#/components/schemas/CreateToolRequest' description: "Request body for creating a new single prompt agent, including its instructions,\ \ welcome message configuration, runtime settings, and available tools." CreateAgentSettingsRequest: type: object properties: language: type: string description: The language your customers will primarily speak during calls. example: en_US default: en_US enum: - multi_nova3 - multi_nova2 - en - en_US - en_AU - en_GB - en_NZ - en_IN - hi - de - de_CH - nl - sv - sv_SE - da - da_DK - es - es_419 - fr - fr_CA - pt - pt_BR - pt_PT - it - tr - no - id - bg - ca - zh - zh_CN - zh_Hans - zh_TW - zh_Hant - zh_HK - cs - et - fi - nl_BE - el - hu - ja - ko - ko_KR - lv - lt - ms - pl - ro - ru - sk - th - th_TH - uk - vi aiStartsConversation: type: boolean description: "If true the AI agent will initiate the conversation immediately\ \ when the call connects. If false the call will connect silently, waiting\ \ for the customer to speak first before the AI responds" example: true default: true backgroundSound: type: string description: Add ambient background audio during the call. example: keyboard_typing default: none enum: - keyboard_typing - office_ambience - none globalPrompt: type: string description: "A global system prompt that is applied to every conversation\ \ to define the agent’s overall behavior, tone, and constraints." example: You are a professional virtual assistant. Always respond politely and keep answers concise. remindersIntervalDuration: maximum: 60 minimum: 10 type: integer description: Interval (in seconds) after which a follow-up reminder is automatically sent if the user does not respond. format: int32 example: 15 default: 10 remindersLimit: maximum: 10 minimum: 0 type: integer description: Maximum number of follow-up reminders to send when the user does not respond. Set to 0 to disable reminders. format: int32 example: 3 default: 4 endCallOnSilenceDuration: maximum: 30.0 exclusiveMaximum: false minimum: 0.1 exclusiveMinimum: false type: number description: Specifies the duration of continuous silence (in minutes) after which the call will be automatically ended. format: float example: 30.0 default: 5.0 maxCallDuration: maximum: 120 minimum: 1 type: integer description: Maximum call duration (in minutes) before the call is automatically terminated. format: int32 example: 40 default: 60 llmModel: type: string description: "The language model that powers the AI's responses. To use\ \ OpenAI priority tier models, append '-fast-tier' to the model name (e.g.,\ \ 'gpt-4o-mini-fast-tier')." example: gpt-4o-mini default: gpt-4o-mini enum: - gpt-5.2 - gpt-5.2-fast-tier - gpt-5.1 - gpt-5.1-fast-tier - gpt-5 - gpt-5-fast-tier - gpt-5-mini - gpt-5-mini-fast-tier - gpt-5-nano - gpt-4.1 - gpt-4.1-fast-tier - gpt-4.1-mini - gpt-4.1-mini-fast-tier - gpt-4.1-nano - gpt-4.1-nano-fast-tier - gpt-4o - gpt-4o-fast-tier - gpt-4o-mini - gpt-4o-mini-fast-tier - claude-haiku-4-5-20251001 - claude-sonnet-4-5-20250929 - claude-sonnet-4-20250514 - gemini-3.1-flash-lite-preview - gemini-3-flash-preview - gemini-2.5-flash-lite - gemini-2.5-flash llmTemperature: maximum: 1.0 exclusiveMaximum: false minimum: 0.0 exclusiveMinimum: false type: number description: "Controls randomness in the model's output. Lower values make\ \ responses more deterministic; higher values make them more creative.\ \ If not provided, the default value is derived from the selected llmModel." format: double example: 0.5 llmTopP: maximum: 1.0 exclusiveMaximum: false minimum: 0.0 exclusiveMinimum: false type: number description: "Controls how diverse the output is by selecting from the most\ \ probable tokens within a probability limit. Lower values make responses\ \ more focused. If not provided, the default value is derived from the\ \ selected llmModel." format: double example: 0.5 llmTopK: maximum: 200 minimum: 0 type: integer description: "Limits token selection to the top-k most probable tokens.\ \ Lower values make output more deterministic; higher values increase\ \ variation. If not provided, the default value is derived from the selected\ \ llmModel" format: int32 example: 40 voiceId: type: string description: This is the AI's speaking voice id. example: elevenlabs_SGbOfpm28edC83pZ9iGb default: elevenlabs_EXAVITQu4vr4xnSDxMaL voiceModelId: type: string description: "Specifies the text-to-speech (TTS) model used by the agent\ \ to generate spoken audio responses. Different models may vary in voice\ \ quality, latency, language support, and naturalness." example: eleven_turbo_v2_5 default: eleven_turbo_v2_5 enum: - eleven_multilingual_v2 - eleven_flash_v2_5 - eleven_turbo_v2_5 - eleven_turbo_v2 - eleven_flash_v2 - eleven_multilingual_v1 - eleven_monolingual_v1 - tts-1 - tts-1-hd - gpt-4o-mini-tts - sonic - sonic-2 - sonic-lite - sonic-preview - sonic-turbo - arcana - mist - mistv2 - octave2_multi - inworld-tts-1 - inworld-tts-1-max ttsSpeed: maximum: 2.0 exclusiveMaximum: false minimum: 0.6 exclusiveMinimum: false type: number description: "Controls the speech playback speed. Lower values make speech\ \ slower; higher values make it faster. If not provided, the default value\ \ is derived from the selected voiceModel." format: double example: 0.7 ttsTemperature: maximum: 2 minimum: 0 type: number description: "Controls variation in speech delivery. Lower values make speech\ \ more consistent; higher values add more expressiveness. If not provided,\ \ the default value is derived from the selected voiceModel." format: double example: 0.5 ttsVolume: maximum: 2.0 exclusiveMaximum: false minimum: 0.5 exclusiveMinimum: false type: number description: "Controls the output audio volume. Lower values make it quieter;\ \ higher values make it louder. If not provided, the default value is\ \ derived from the selected voiceModel." format: double example: 0.5 aiStartsSpeakingPlan: maximum: 1.0 exclusiveMaximum: false minimum: 0.0 exclusiveMinimum: false type: number description: How quickly AI starts speaking after user input. format: double example: 0.5 default: 1.0 aiStopsSpeakingPlan: maximum: 1.0 exclusiveMaximum: false minimum: 0.0 exclusiveMinimum: false type: number description: How quickly AI stops speaking when interrupted. format: double example: 0.5 default: 1.0 ivrHangup: type: boolean description: Determines whether the call should be automatically disconnected when an IVR system is detected during the call. example: true default: false agentTimezone: type: string description: The timezone of the agent in IANA format. Used to contextualize time-sensitive responses and scheduling. example: Asia/Kolkata default: UTC autoVolumeNormalization: type: boolean description: "If true, it keeps the user's microphone volume consistent\ \ regardless of distance or loudness." example: true default: true backgroundNoiseFilter: type: boolean description: "If true, it removes hums, buzzes, and rumbles from the audio\ \ signal." example: true default: false echoCancellation: type: boolean description: "If true, it stops the AI's audio from looping back into the\ \ microphone." example: true default: true enablePostConversationAnalysis: type: boolean description: Indicates whether post-conversation analysis should be performed to extract insights after the conversation ends. example: true default: false postConversationAnalysisLlmModel: type: string description: The language model that powers the AI's post-conversation analysis. example: gpt-4o-mini default: gpt-4o-mini enum: - gpt-5.2 - gpt-5.2-fast-tier - gpt-5.1 - gpt-5.1-fast-tier - gpt-5 - gpt-5-fast-tier - gpt-5-mini - gpt-5-mini-fast-tier - gpt-5-nano - gpt-4.1 - gpt-4.1-fast-tier - gpt-4.1-mini - gpt-4.1-mini-fast-tier - gpt-4.1-nano - gpt-4.1-nano-fast-tier - gpt-4o - gpt-4o-fast-tier - gpt-4o-mini - gpt-4o-mini-fast-tier - claude-haiku-4-5-20251001 - claude-sonnet-4-5-20250929 - claude-sonnet-4-20250514 - gemini-3.1-flash-lite-preview - gemini-3-flash-preview - gemini-2.5-flash-lite - gemini-2.5-flash postConversationAnalysis: type: array description: List of configurations defining what insights should be extracted after the conversation ends. items: $ref: '#/components/schemas/PostConversationAnalysisRequest' webhooks: type: array description: List of webhook configurations that define external endpoints to be notified on specific events. items: $ref: '#/components/schemas/WebhookConfig' description: "Configuration settings that define the agent’s runtime behavior,\ \ including voice, llm model and other operational settings." PostConversationAnalysisRequest: required: - dataType - insightInstructions - insightName type: object properties: insightName: type: string description: A Unique name of the insight that will be generated from the conversation. example: conversation summary insightInstructions: type: string description: Instructions or prompt that define how the insight should be generated from the conversation. dataType: type: string description: Defines the expected data type of the generated insight result. example: string enum: - string - boolean - number - selector options: type: array description: List of allowed selectable values. Required only when dataType is selector. example: - Interested - Not Interested - Follow Up Later items: type: string example: "[\"Interested\",\"Not Interested\",\"Follow Up Later\"]" description: List of configurations defining what insights should be extracted after the conversation ends. WebhookConfig: required: - events - name - url type: object properties: name: maxLength: 128 minLength: 1 type: string description: "Human-readable name for this webhook. Used to identify it\ \ in listings and dashboards. Does not need to be unique, but a descriptive\ \ name helps distinguish multiple webhooks on the same agent." example: Call Events - Production url: pattern: https?://.+ type: string description: HTTPS endpoint that will receive event payloads as HTTP POST requests. Must be publicly reachable. The system expects an HTTP 2xx response within the configured timeout to confirm delivery. Non-2xx responses or timeouts are treated as delivery failures. example: https://yourapp.com/webhooks/sigmamind events: uniqueItems: true type: array description: Set of event types that will trigger a delivery to this webhook. 'conversation_started' fires when an agent session begins. 'conversation_ended' fires when a session closes. 'conversation_analysed' fires when post-call analysis is complete. At least one event must be specified. Only events in this set will be sent — all others are silently ignored. example: - conversation_started - conversation_ended items: type: string example: "[\"conversation_started\",\"conversation_ended\"]" enum: - conversation_started - conversation_ended - conversation_analysed description: List of webhook configurations that define external endpoints to be notified on specific events. CreateToolRequest: required: - type type: object properties: type: type: string description: "The type determines the tool’s behavior and configuration\ \ schema, such as call transfer, variable extraction, IVR navigation,\ \ integrations, etc." toolName: type: string description: "A unique name used to identify the tool within an agent. The name may contain only alphanumeric characters and underscores (_). If not provided, a name will be generated automatically. Tool names must be unique within the same agent." instruction: maxLength: 10000 minLength: 0 type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." discriminator: propertyName: type mapping: voice_transfer_call: '#/components/schemas/VoiceTransferCallTool' extract_variables: '#/components/schemas/ExtractVariablesTool' ivr_navigator: '#/components/schemas/IvrNavigatorTool' voice_end_call: '#/components/schemas/VoiceEndCallTool' integration_tool: '#/components/schemas/IntegrationTool' oneOf: - $ref: '#/components/schemas/VoiceTransferCallTool' - $ref: '#/components/schemas/ExtractVariablesTool' - $ref: '#/components/schemas/IvrNavigatorTool' - $ref: '#/components/schemas/VoiceEndCallTool' - $ref: '#/components/schemas/IntegrationTool' CreateAgentResponse: type: object properties: agentId: type: string description: Id of the agent. example: SPIlVscbB0kkXBvZ agentName: type: string description: Human-readable name of the agent used to identify it in the dashboard and APIs. example: Auralis instructions: type: string description: "Core system prompt that defines the agent’s behavior, personality,\ \ tone, response style, goals, and task handling logic. These instructions\ \ guide how the agent interacts with users and responds during conversations." example: You are a helpful customer support assistant. Answer concisely and professionally. welcomeMessageType: type: string description: "Determines how the agent’s welcome message is generated. Use\ \ 'static' to send a fixed predefined message, or 'prompt' to dynamically\ \ generate the welcome message using AI instructions." example: static default: static enum: - static - prompt welcomeMessage: type: string description: "The content of the welcome message. If 'welcomeMessageType'\ \ is 'static', this contains the exact message shown to the user. If it\ \ is 'prompt', this contains the prompt used to generate the welcome message\ \ dynamically." example: Welcome to our service! How can I assist you today? agentSettings: $ref: '#/components/schemas/CreateAgentSettingsResponse' tools: type: array items: $ref: '#/components/schemas/CreateToolResponse' CreateAgentSettingsResponse: type: object properties: language: type: string description: The language your customers will primarily speak during calls. example: en_US default: en_US aiStartsConversation: type: boolean description: "If true the AI agent will initiate the conversation immediately\ \ when the call connects. If false the call will connect silently, waiting\ \ for the customer to speak first before the AI responds" example: true default: true backgroundSound: type: string description: Add ambient background audio during the call. example: keyboard_typing default: none enum: - keyboard_typing - office_ambience - none globalPrompt: type: string description: "A global system prompt that is applied to every conversation\ \ to define the agent’s overall behavior, tone, and constraints." example: You are a professional virtual assistant. Always respond politely and keep answers concise. remindersIntervalDuration: type: integer description: Interval (in seconds) after which a follow-up reminder is automatically sent if the user does not respond. format: int32 example: 15 default: 10 remindersLimit: type: integer description: Maximum number of follow-up reminders to send when the user does not respond.Set to 0 to disable reminders. format: int32 example: 3 default: 4 endCallOnSilenceDuration: type: number description: Specifies the duration of continuous silence (in minutes) after which the call will be automatically ended. format: float example: 30.0 default: 5 maxCallDuration: type: integer description: Maximum call duration (in minutes) before the call is automatically terminated. format: int32 example: 40 default: 60 llmModel: type: string description: The language model that powers the AI's responses. example: gpt-4o-mini default: gpt-4o-mini llmTemperature: type: number description: "Controls randomness in the model's output. Lower values make\ \ responses more deterministic; higher values make them more creative.\ \ If not provided, the default value is derived from the selected llmModel." format: double example: 0.5 llmTopP: type: number description: "Controls how diverse the output is by selecting from the most\ \ probable tokens within a probability limit. Lower values make responses\ \ more focused. If not provided, the default value is derived from the\ \ selected llmModel." format: double example: 0.5 llmTopK: type: integer description: "Limits token selection to the top-k most probable tokens.\ \ Lower values make output more deterministic; higher values increase\ \ variation. If not provided, the default value is derived from the selected\ \ llmModel" format: int32 example: 40 voiceId: type: string description: This is the AIs speaking voice id. example: elevenlabs_SGbOfpm28edC83pZ9iGb default: elevenlabs_EXAVITQu4vr4xnSDxMaL voiceModelId: type: string description: This is the AIs text to speech engine version. example: eleven_turbo_v2_5 default: eleven_turbo_v2_5 ttsSpeed: type: number description: "Controls the speech playback speed. Lower values make speech\ \ slower; higher values make it faster. If not provided, the default value\ \ is derived from the selected voiceModel." format: double example: 0.7 ttsTemperature: type: number description: "Controls variation in speech delivery. Lower values make speech\ \ more consistent; higher values add more expressiveness. If not provided,\ \ the default value is derived from the selected voiceModel." format: double example: 0.5 ttsVolume: type: number description: "Controls the output audio volume. Lower values make it quieter;\ \ higher values make it louder. If not provided, the default value is\ \ derived from the selected voiceModel." format: double example: 0.5 aiStartsSpeakingPlan: type: number description: How quickly AI starts speaking after user input. format: double example: 0.5 default: 1.0 aiStopsSpeakingPlan: type: number description: How quickly AI stops speaking when interrupted. format: double example: 0.5 default: 1.0 ivrHangup: type: boolean description: Determines whether the call should be automatically disconnected when an IVR system is detected during the call. example: true default: false agentTimezone: type: string description: The timezone of the agent in IANA format. Used to contextualize time-sensitive responses and scheduling. example: Asia/Kolkata default: UTC autoVolumeNormalization: type: boolean description: "If true, it keeps the user's microphone volume consistent\ \ regardless of distance or loudness." example: true default: true backgroundNoiseFilter: type: boolean description: "If true, it removes hums, buzzes, and rumbles from the audio\ \ signal." example: true default: false echoCancellation: type: boolean description: "If true, it stops the AI's audio from looping back into the\ \ microphone." example: true default: true enablePostConversationAnalysis: type: boolean description: Indicates whether post-conversation analysis should be performed to extract insights after the conversation ends. example: true default: false postConversationAnalysisLlmModel: type: string description: The language model that powers the AI's post-conversation analysis. example: gpt-4o-mini default: gpt-4o-mini postConversationAnalysis: type: array description: List of configurations defining what insights should be extracted after the conversation ends. items: $ref: '#/components/schemas/PostConversationAnalysisRequest' webhooks: type: array description: List of webhook configurations that define external endpoints to be notified on specific events. items: $ref: '#/components/schemas/WebhookConfigResponse' description: "Configuration settings that define the agent’s runtime behavior,\ \ including voice, llm model and other operational settings." CreateToolResponse: type: object properties: type: type: string description: "The type determines the tool’s behavior and configuration\ \ schema, such as call transfer, variable extraction, IVR navigation,\ \ integrations, etc." nodeId: type: string description: The unique identifier of the tool within the agent. toolName: type: string description: A unique name used to identify the tool within an agent. Use this name to reference the tool within the agent. instruction: type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." discriminator: propertyName: type mapping: voice_transfer_call: '#/components/schemas/VoiceTransferCallToolResponse' extract_variables: '#/components/schemas/ExtractVariablesToolResponse' ivr_navigator: '#/components/schemas/IvrNavigatorToolResponse' voice_end_call: '#/components/schemas/VoiceEndCallToolResponse' integration_tool: '#/components/schemas/IntegrationToolAgentResponse' oneOf: - $ref: '#/components/schemas/VoiceTransferCallToolResponse' - $ref: '#/components/schemas/ExtractVariablesToolResponse' - $ref: '#/components/schemas/IvrNavigatorToolResponse' - $ref: '#/components/schemas/VoiceEndCallToolResponse' - $ref: '#/components/schemas/IntegrationToolAgentResponse' UpdateAgentRequest: type: object description: "Request body for updating an existing single prompt agent, including its instructions,\ \ welcome message configuration, runtime settings, and available tools." properties: agentName: type: string description: Human-readable name of the agent used to identify it in the dashboard and APIs. example: Auralis instructions: type: string description: "Core system prompt that defines the agent’s behavior, personality,\ \ tone, response style, goals, and task handling logic. These instructions\ \ guide how the agent interacts with users and responds during conversations." example: You are a helpful customer support assistant. Answer concisely and professionally. welcomeMessageType: type: string description: "Determines how the agent’s welcome message is generated. Use\ \ 'static' to send a fixed predefined message, or 'prompt' to dynamically\ \ generate the welcome message using AI instructions." example: static default: static enum: - static - prompt welcomeMessage: type: string description: "The content of the welcome message. If 'welcomeMessageType'\ \ is 'static', this contains the exact message shown to the user. If it\ \ is 'prompt', this contains the prompt used to generate the welcome message\ \ dynamically." example: Welcome to our service! How can I assist you today? agentSettings: $ref: '#/components/schemas/UpdateAgentSettingsRequest' tools: type: array items: $ref: '#/components/schemas/UpdateToolRequest' UpdateAgentSettingsRequest: type: object properties: language: type: string description: The language your customers will primarily speak during calls. example: en_US default: en_US enum: - multi_nova3 - multi_nova2 - en - en_US - en_AU - en_GB - en_NZ - en_IN - hi - de - de_CH - nl - sv - sv_SE - da - da_DK - es - es_419 - fr - fr_CA - pt - pt_BR - pt_PT - it - tr - no - id - bg - ca - zh - zh_CN - zh_Hans - zh_TW - zh_Hant - zh_HK - cs - et - fi - nl_BE - el - hu - ja - ko - ko_KR - lv - lt - ms - pl - ro - ru - sk - th - th_TH - uk - vi aiStartsConversation: type: boolean description: "If true the AI agent will initiate the conversation immediately\ \ when the call connects. If false the call will connect silently, waiting\ \ for the customer to speak first before the AI responds" example: true default: true backgroundSound: type: string description: Add ambient background audio during the call. example: keyboard_typing default: none enum: - keyboard_typing - office_ambience - none globalPrompt: type: string description: "A global system prompt that is applied to every conversation\ \ to define the agent’s overall behavior, tone, and constraints." example: You are a professional virtual assistant. Always respond politely and keep answers concise. remindersIntervalDuration: maximum: 60 minimum: 10 type: integer description: Interval (in seconds) after which a follow-up reminder is automatically sent if the user does not respond. format: int32 example: 15 default: 10 remindersLimit: maximum: 10 minimum: 0 type: integer description: Maximum number of follow-up reminders to send when the user does not respond. Set to 0 to disable reminders. format: int32 example: 3 default: 4 endCallOnSilenceDuration: maximum: 30.0 exclusiveMaximum: false minimum: 0.1 exclusiveMinimum: false type: number description: Specifies the duration of continuous silence (in minutes) after which the call will be automatically ended. format: float example: 30.0 default: 5.0 maxCallDuration: maximum: 120 minimum: 1 type: integer description: Maximum call duration (in minutes) before the call is automatically terminated. format: int32 example: 40 default: 60 llmModel: type: string description: "The language model that powers the AI's responses. To use\ \ OpenAI priority tier models, append '-fast-tier' to the model name (e.g.,\ \ 'gpt-4o-mini-fast-tier')." example: gpt-4o-mini default: gpt-4o-mini enum: - gpt-5.2 - gpt-5.2-fast-tier - gpt-5.1 - gpt-5.1-fast-tier - gpt-5 - gpt-5-fast-tier - gpt-5-mini - gpt-5-mini-fast-tier - gpt-5-nano - gpt-4.1 - gpt-4.1-fast-tier - gpt-4.1-mini - gpt-4.1-mini-fast-tier - gpt-4.1-nano - gpt-4.1-nano-fast-tier - gpt-4o - gpt-4o-fast-tier - gpt-4o-mini - gpt-4o-mini-fast-tier - claude-haiku-4-5-20251001 - claude-sonnet-4-5-20250929 - claude-sonnet-4-20250514 - gemini-3.1-flash-lite-preview - gemini-3-flash-preview - gemini-2.5-flash-lite - gemini-2.5-flash llmTemperature: maximum: 1.0 exclusiveMaximum: false minimum: 0.0 exclusiveMinimum: false type: number description: "Controls randomness in the model's output. Lower values make\ \ responses more deterministic; higher values make them more creative.\ \ If not provided, the default value is derived from the selected llmModel." format: double example: 0.5 llmTopP: maximum: 1.0 exclusiveMaximum: false minimum: 0.0 exclusiveMinimum: false type: number description: "Controls how diverse the output is by selecting from the most\ \ probable tokens within a probability limit. Lower values make responses\ \ more focused. If not provided, the default value is derived from the\ \ selected llmModel." format: double example: 0.5 llmTopK: maximum: 200 minimum: 0 type: integer description: "Limits token selection to the top-k most probable tokens.\ \ Lower values make output more deterministic; higher values increase\ \ variation. If not provided, the default value is derived from the selected\ \ llmModel" format: int32 example: 40 voiceId: type: string description: This is the AI's speaking voice id. example: elevenlabs_SGbOfpm28edC83pZ9iGb default: elevenlabs_EXAVITQu4vr4xnSDxMaL voiceModelId: type: string description: "Specifies the text-to-speech (TTS) model used by the agent\ \ to generate spoken audio responses. Different models may vary in voice\ \ quality, latency, language support, and naturalness." example: eleven_turbo_v2_5 default: eleven_turbo_v2_5 enum: - eleven_multilingual_v2 - eleven_flash_v2_5 - eleven_turbo_v2_5 - eleven_turbo_v2 - eleven_flash_v2 - eleven_multilingual_v1 - eleven_monolingual_v1 - tts-1 - tts-1-hd - gpt-4o-mini-tts - sonic - sonic-2 - sonic-lite - sonic-preview - sonic-turbo - arcana - mist - mistv2 - octave2_multi - inworld-tts-1 - inworld-tts-1-max ttsSpeed: maximum: 2.0 exclusiveMaximum: false minimum: 0.6 exclusiveMinimum: false type: number description: Controls the speech playback speed. Lower values make speech slower; higher values make it faster. format: double example: 0.7 ttsTemperature: maximum: 2 minimum: 0 type: number description: Controls variation in speech delivery. Lower values make speech more consistent; higher values add more expressiveness. format: double example: 0.5 ttsVolume: maximum: 2.0 exclusiveMaximum: false minimum: 0.5 exclusiveMinimum: false type: number description: Controls the output audio volume. Lower values make it quieter; higher values make it louder. format: double example: 0.5 default: 0 aiStartsSpeakingPlan: maximum: 1 minimum: 0 type: number description: How quickly AI starts speaking after user input. format: double example: 0.5 default: 1 aiStopsSpeakingPlan: maximum: 1 minimum: 0 type: number description: How quickly AI stops speaking when interrupted. format: double example: 0.5 default: 1 ivrHangup: type: boolean description: Determines whether the call should be automatically disconnected when an IVR system is detected during the call. example: true default: false agentTimezone: type: string description: The timezone of the agent in IANA format. Used to contextualize time-sensitive responses and scheduling. example: Asia/Kolkata default: UTC autoVolumeNormalization: type: boolean description: "If true, it keeps the user's microphone volume consistent\ \ regardless of distance or loudness." example: true default: true backgroundNoiseFilter: type: boolean description: "If true, it removes hums, buzzes, and rumbles from the audio\ \ signal." example: true default: false echoCancellation: type: boolean description: "If true, it stops the AI's audio from looping back into the\ \ microphone." example: true default: true enablePostConversationAnalysis: type: boolean description: Indicates whether post-conversation analysis should be performed to extract insights after the conversation ends. example: true default: false postConversationAnalysisLlmModel: type: string description: The language model that powers the AI's post-conversation analysis. example: gpt-4o-mini default: gpt-4o-mini enum: - gpt-5.2 - gpt-5.2-fast-tier - gpt-5.1 - gpt-5.1-fast-tier - gpt-5 - gpt-5-fast-tier - gpt-5-mini - gpt-5-mini-fast-tier - gpt-5-nano - gpt-4.1 - gpt-4.1-fast-tier - gpt-4.1-mini - gpt-4.1-mini-fast-tier - gpt-4.1-nano - gpt-4.1-nano-fast-tier - gpt-4o - gpt-4o-fast-tier - gpt-4o-mini - gpt-4o-mini-fast-tier - claude-haiku-4-5-20251001 - claude-sonnet-4-5-20250929 - claude-sonnet-4-20250514 - gemini-3.1-flash-lite-preview - gemini-3-flash-preview - gemini-2.5-flash-lite - gemini-2.5-flash postConversationAnalysis: type: array description: List of configurations defining what insights should be extracted after the conversation ends. items: $ref: '#/components/schemas/PostConversationAnalysisRequest' webhooks: type: array description: List of webhook configurations that define external endpoints to be notified on specific events. items: $ref: '#/components/schemas/WebhookConfigUpdateRequest' description: "Request body for updating an existing AI agent, including its\ \ instructions, welcome message configuration, runtime settings, and available\ \ tools." WebhookConfigUpdateRequest: required: - events - name - url type: object properties: webhookId: type: string description: A unique identifier for the webhook. example: wh_BUbkx3PsbzQm5V10 name: type: string description: "Human-readable name for this webhook. Used to identify it\ \ in listings and dashboards. Does not need to be unique, but a descriptive\ \ name helps distinguish multiple webhooks on the same agent." example: Call Events - Production url: pattern: https?://.+ type: string description: HTTPS endpoint that will receive event payloads as HTTP POST requests. Must be publicly reachable. The system expects an HTTP 2xx response within the configured timeout to confirm delivery. Non-2xx responses or timeouts are treated as delivery failures. example: https://yourapp.com/webhooks/sigmamind events: uniqueItems: true type: array description: Set of event types that will trigger a delivery to this webhook. 'conversation_started' fires when an agent session begins. 'conversation_ended' fires when a session closes. 'conversation_analysed' fires when post-call analysis is complete. At least one event must be specified. Only events in this set will be sent — all others are silently ignored. example: - conversation_started - conversation_ended items: type: string enum: - conversation_started - conversation_ended - conversation_analysed description: List of webhook configurations that define external endpoints to be notified on specific events. TransferSettings: required: - transferType type: object properties: transferType: type: string description: "Type of transfer to perform. 'warm' keeps the current agent\ \ connected during the transfer, while 'cold' disconnects the agent immediately\ \ after initiating the transfer." enum: - warm - cold default: warm ringingDuration: maximum: 60 minimum: 25 type: integer description: Specifies the maximum duration (in seconds) to wait for the call to be answered. format: int32 example: 40 default: 30 waitForParticipantAnswer: type: boolean description: "If true, agent will wait for the new participant to answer\ \ the call." default: true enableWhisperMessage: type: boolean description: "If true, a whisper message will be played privately to the\ \ destination participant before the caller is connected." default: true whisperMessage: type: string description: "The content of the whisper message. Its interpretation depends\ \ on whisperMessageType. If the type is 'static', this text is played\ \ directly. If the type is 'prompt', the text is treated as a prompt that\ \ the system uses to dynamically generate the whisper message." whisperMessageType: type: string description: "Defines how the whisperMessage should be interpreted. 'static'\ \ means the message is used as-is, while 'prompt' means the message is\ \ treated as a prompt for generating the final whisper message." default: static enum: - static - prompt enableThreeWayMessage: type: boolean description: "If true, a message will be delivered once the call becomes\ \ a three-way conversation between the caller, the current agent, and\ \ the destination participant." default: true threeWayMessage: type: string description: "The content of the message delivered during the three-way\ \ connection. Its interpretation depends on threeWayMessageType. If 'static',\ \ the message is used directly. If 'prompt', it is treated as a prompt\ \ for generating the final message." threeWayMessageType: type: string description: "Defines how the threeWayMessage should be interpreted. 'static'\ \ means the message is used as-is, while 'prompt' means the message is\ \ treated as a prompt for generating the final message." default: static enum: - static - prompt customHeaders: type: object description: Send custom header key and values along with call transfer. additionalProperties: oneOf: - type: string - type: number - type: boolean - type: object - type: array description: Configuration for the call transfer behaviour Variable: required: - description - variableName type: object properties: variableName: type: string description: Name of the variable example: customer_name dataType: type: string description: Data type of the variable to be extracted. example: dateTimeIso8601 enum: - text - boolean - number - dateTimeIso8601 description: type: string description: Description of what this variable represents description: "Defines a variable to be extracted from a conversation, including\ \ its name, data type, and description. " VoiceEndCallTool: required: - type type: object description: Ends the current voice call properties: type: type: string example: voice_end_call enum: - voice_end_call instruction: type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." VoiceTransferCallTool: required: - transferTo - type type: object description: Transfers the active voice call to another number properties: type: type: string example: voice_transfer_call enum: - voice_transfer_call instruction: type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." transferToRouting: type: string description: "Defines how the destination for the call transfer is determined.\ \ Use 'static' to always transfer to a fixed phone number. Use 'dynamic'\ \ to determine the destination at runtime based on conditions or extracted\ \ variables (e.g., user intent such as OPD, radiology, etc.)." example: static default: static enum: - static - dynamic transferTo: type: string description: "Destination for the call transfer. If transferToRouting\ \ is 'static', provide a valid E.164 formatted phone number. If transferToRouting\ \ is 'dynamic', provide instructions or a dynamic variable placeholder\ \ to resolve the destination at runtime. For example: If the user wants\ \ to connect with OPD, transfer to {{dynamic_variable}} or a specific\ \ number. If the user wants to connect with radiology, transfer to {{dynamic_variable}}\ \ or a specific number." example: +9187788XXXXX extensionNumber: pattern: "^[0-9]{1,10}$|^\\{\\{.+\\}\\}$" type: string description: "Optional extension number to dial after the call is transferred.\ \ This is typically used in IVR systems to reach a specific department\ \ or user." example: "1234" transferSettings: $ref: '#/components/schemas/TransferSettings' ExtractVariablesTool: required: - type - variables type: object description: Extracts and stores named variables from the conversation properties: type: type: string example: extract_variables enum: - extract_variables instruction: type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." variables: type: array description: List of variables to extract from the conversation items: $ref: '#/components/schemas/Variable' IvrNavigatorTool: required: - type type: object description: This tool is used to navigate through IVR. properties: type: type: string example: ivr_navigator enum: - ivr_navigator instruction: type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." ivrStartsConversation: type: boolean description: Indicates whether the call is initiated by an IVR (Interactive Voice Response) system. Set to true when the interaction begins with an automated IVR prompt before connecting to an agent or system flow. example: true default: true pauseDelay: maximum: 30000 minimum: 500 type: integer description: Specifies the duration (in milliseconds) to wait before assuming the IVR system has finished its input or prompt. This delay helps ensure that subsequent actions are triggered only after the IVR interaction is complete. format: int64 example: 4000 default: 2000 IntegrationTool: required: - toolId - type type: object description: "Triggers an action from a connected app (e.g. Shopify, HubSpot)" properties: type: type: string description: Type of the tool example: integration_tool enum: - integration_tool instruction: type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." toolId: type: string description: toolId of the specific integration tool to execute example: tool_0QqvBhLiudhHyMDC speakWhileWaiting: type: boolean description: "If enabled, the agent will provide filler or holding speech\ \ while waiting for the tool to respond." example: true default: true placeholders: type: object additionalProperties: type: string description: "Defines values for the placeholders expected by the integration\ \ tool. Each key represents a placeholder name and its value can either\ \ be a static value or a dynamic variable using the format {{variable_name}}\ \ to inject runtime data." description: "Defines values for the placeholders expected by the integration\ \ tool. Each key represents a placeholder name and its value can either\ \ be a static value or a dynamic variable using the format {{variable_name}}\ \ to inject runtime data." mapVariables: type: object additionalProperties: type: string description: Maps the response paths of the tool to dynamic variables. Each key is the variable name and the value is the mapped response path. description: Maps the response paths of the tool to dynamic variables. Each key is the variable name and the value is the mapped response path. ExtractVariablesToolResponse: type: object properties: type: type: string example: extract_variables enum: - extract_variables nodeId: type: string description: The unique identifier of the tool within the agent. toolName: type: string description: A unique name used to identify the tool within an agent. Use this name to reference the tool within the agent. instruction: type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." variables: type: array description: List of variables to extract from the conversation items: $ref: '#/components/schemas/Variable' description: Extracts and stores named variables from the conversation IvrNavigatorToolResponse: type: object properties: type: type: string example: ivr_navigator enum: - ivr_navigator nodeId: type: string description: The unique identifier of the tool within the agent. toolName: type: string description: A unique name used to identify the tool within an agent. Use this name to reference the tool within the agent. instruction: type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." ivrStartsConversation: type: boolean description: Indicates whether the call is initiated by an IVR (Interactive Voice Response) system. Set to true when the interaction begins with an automated IVR prompt before connecting to an agent or system flow. example: true default: true pauseDelay: maximum: 30000 minimum: 500 type: integer description: Specifies the duration (in milliseconds) to wait before assuming the IVR system has finished its input or prompt. This delay helps ensure that subsequent actions are triggered only after the IVR interaction is complete. format: int64 example: 4000 default: 2000 description: This tool is used to navigate through IVR. VoiceEndCallToolResponse: type: object properties: type: type: string example: voice_end_call enum: - voice_end_call nodeId: type: string description: The unique identifier of the tool within the agent. toolName: type: string description: A unique name used to identify the tool within an agent. Use this name to reference the tool within the agent. instruction: type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." description: Ends the current voice call VoiceTransferCallToolResponse: type: object properties: type: type: string example: voice_transfer_call enum: - voice_transfer_call nodeId: type: string description: The unique identifier of the tool within the agent. toolName: type: string description: A unique name used to identify the tool within an agent. Use this name to reference the tool within the agent. instruction: type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." transferToRouting: type: string description: "Defines how the destination for the call transfer is determined.\ \ Use 'static' to always transfer to a fixed phone number. Use 'dynamic'\ \ to determine the destination at runtime based on conditions or extracted\ \ variables (e.g., user intent such as OPD, radiology, etc.)." example: static default: static enum: - static - dynamic transferTo: type: string description: "Destination for the call transfer. If transferToRouting is\ \ 'static', provide a valid E.164 formatted phone number. If transferToRouting\ \ is 'dynamic', provide instructions or a dynamic variable placeholder\ \ to resolve the destination at runtime. For example: If the user wants\ \ to connect with OPD, transfer to {{dynamic_variable}} or a specific\ \ number. If the user wants to connect with radiology, transfer to {{dynamic_variable}}\ \ or a specific number." example: +9187788XXXXX extensionNumber: type: string description: Optional extension number to dial after the call is transferred. This is typically used in IVR systems to reach a specific department or user. example: "1234" transferSettings: $ref: '#/components/schemas/TransferSettings' description: Transfers the active voice call to another number IntegrationToolAgentResponse: type: object properties: type: type: string description: Type of the tool example: integration_tool enum: - integration_tool nodeId: type: string description: The unique identifier of the tool within the agent. toolName: type: string description: A unique name used to identify the tool within an agent. Use this name to reference the tool within the agent. instruction: type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." toolId: type: string description: The specific tool to execute example: tool_0QqvBhLiudhHyMDC speakWhileWaiting: type: boolean description: "If enabled, the agent will provide filler or holding speech\ \ while waiting for the tool to respond" example: true default: true placeholders: type: object additionalProperties: type: string description: "Defines values for the placeholders expected by the integration\ \ tool. Each key represents a placeholder name and its value can either\ \ be a static value or a dynamic variable using the format {{variable_name}}\ \ to inject runtime data." description: "Defines values for the placeholders expected by the integration\ \ tool. Each key represents a placeholder name and its value can either\ \ be a static value or a dynamic variable using the format {{variable_name}}\ \ to inject runtime data." mapVariables: type: object additionalProperties: type: string description: Maps the response paths of the tool to dynamic variables. Each key is the variable name and the value is the mapped response path description: Maps the response paths of the tool to dynamic variables. Each key is the variable name and the value is the mapped response path description: "Triggers an action from a connected app (e.g. Shopify, HubSpot)" UpdateToolRequest: required: - type type: object properties: type: type: string description: "The type determines the tool’s behavior and configuration\ \ schema, such as call transfer, variable extraction, IVR navigation,\ \ integrations, etc." nodeId: type: string description: The unique identifier of an existing tool within the agent. If provided, the corresponding tool will be updated. If omitted, a new tool will be created and added to the agent. toolName: type: string description: "A unique name used to identify the tool within an agent. The name may contain only alphanumeric characters and underscores (_). If not provided, a name will be generated automatically. Tool names must be unique within the same agent." instruction: maxLength: 10000 minLength: 0 type: string description: "Instructions that define when the agent should invoke this\ \ tool during a conversation. Use this field to describe the scenarios,\ \ user intents, or conditions under which the tool should be triggered." discriminator: propertyName: type mapping: voice_transfer_call: '#/components/schemas/VoiceTransferCallTool' extract_variables: '#/components/schemas/ExtractVariablesTool' ivr_navigator: '#/components/schemas/IvrNavigatorTool' voice_end_call: '#/components/schemas/VoiceEndCallTool' integration_tool: '#/components/schemas/IntegrationTool' oneOf: - $ref: '#/components/schemas/VoiceTransferCallTool' - $ref: '#/components/schemas/ExtractVariablesTool' - $ref: '#/components/schemas/IvrNavigatorTool' - $ref: '#/components/schemas/VoiceEndCallTool' - $ref: '#/components/schemas/IntegrationTool' PaginatedResponseCreateAgentResponse: type: object description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/CreateAgentResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. WebhookConfigResponse: type: object properties: webhookId: type: string description: A unique identifier for the webhook. example: wh_BUbkx3PsbzQm5V10 name: type: string description: "Human-readable name for this webhook. Used to identify it\ \ in listings and dashboards. Does not need to be unique, but a descriptive\ \ name helps distinguish multiple webhooks on the same agent." example: My Webhook url: pattern: https?://.+ type: string description: HTTPS endpoint that will receive event payloads as HTTP POST requests. Must be publicly reachable. The system expects an HTTP 2xx response within the configured timeout to confirm delivery. Non-2xx responses or timeouts are treated as delivery failures. example: https://example.com/webhook secret: type: string description: Secret key used to authenticate webhook payloads. This key should be securely stored and verified on the receiving server. example: mK9vXq2pL8nR5tY1wA3sD6fH0jC4bE7u events: type: array description: Set of event types that will trigger a delivery to this webhook. 'conversation_started' fires when an agent session begins. 'conversation_ended' fires when a session closes. 'conversation_analysed' fires when post-call analysis is complete. At least one event must be specified. Only events in this set will be sent — all others are silently ignored. items: type: string description: List of webhook configurations that define external endpoints to be notified on specific events. AgentToolResponse: type: object properties: integrationId: type: string description: Public identifier of the integration this tool belongs to. example: intg_AuUKK371Spr5 toolId: type: string description: Public identifier of the integration tool. example: tool_X9pLm2Wq8Rt3 toolName: type: string description: Display name of the tool. example: Get Order toolAlias: type: string description: Tool alias used to reference this tool on the agent. example: get_order method: type: string description: HTTP method used when invoking this tool. example: GET endpoint: type: string description: "API endpoint this tool calls. May include {{variable}} placeholders\ \ resolved at runtime." example: "https://my-store.myshopify.com/admin/api/2024-01/orders/{{orderId}}.json" headers: $ref: '#/components/schemas/JsonNode' params: $ref: '#/components/schemas/JsonNode' bodyParams: $ref: '#/components/schemas/JsonNode' bodyParamsType: type: string description: Format of the request body. Raw or JSON. example: JSON enum: - Raw - JSON statusCode: type: integer description: HTTP status code associated with this tool response. format: int32 example: 200 description: An integration tool attached to an agent. PaginatedResponseAgentToolResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/AgentToolResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # Conversational Agent APIs Schemas AgentNodeResponse: type: object properties: nodeId: type: string description: Unique identifier of the node. example: node_wcCIoGrJbw9AlXVk nodeName: type: string description: "Human-readable name of the node. Must be unique within the\ \ agent and contain only letters, numbers, and underscores." example: get_customer_detail nodeType: type: string description: "Type of the node, which determines its behavior and available\ \ configuration." discriminator: propertyName: nodeType mapping: message: '#/components/schemas/MessageNodeResponse' sub_agent: '#/components/schemas/SubAgentNodeResponse' if_else: '#/components/schemas/IfElseNodeResponse' global_condition: '#/components/schemas/GlobalConditionNodeResponse' voice_transfer_call: '#/components/schemas/VoiceTransferCallNodeResponse' extract_variables: '#/components/schemas/ExtractVariablesNodeResponse' ivr_navigator: '#/components/schemas/IvrNavigatorNodeResponse' voice_end_call: '#/components/schemas/VoiceEndCallNodeResponse' integration_tool: '#/components/schemas/IntegrationToolNodeResponse' oneOf: - $ref: '#/components/schemas/MessageNodeResponse' - $ref: '#/components/schemas/SubAgentNodeResponse' - $ref: '#/components/schemas/IfElseNodeResponse' - $ref: '#/components/schemas/GlobalConditionNodeResponse' - $ref: '#/components/schemas/VoiceTransferCallNodeResponse' - $ref: '#/components/schemas/ExtractVariablesNodeResponse' - $ref: '#/components/schemas/IvrNavigatorNodeResponse' - $ref: '#/components/schemas/VoiceEndCallNodeResponse' - $ref: '#/components/schemas/IntegrationToolNodeResponse' ConversationalAgentResponse: type: object properties: agentId: type: string description: The unique identifier of the agent within the system. example: SPIlVscbB0kkXBvZ agentName: type: string description: Human-readable name of the agent used to identify it in the dashboard and APIs. example: Auralis startNodeName: type: string description: The name of the node where the agent workflow starts. example: Welcome startNodeId: type: string description: The unique identifier of the node where the agent workflow starts. example: node_01HXYZ123 agentSettings: $ref: '#/components/schemas/CreateAgentSettingsResponse' nodes: type: array items: $ref: '#/components/schemas/AgentNodeResponse' ExtractVariablesNodeResponse: type: object properties: nodeId: type: string description: Unique identifier of the node. example: node_wcCIoGrJbw9AlXVk nodeName: type: string description: "Human-readable name of the node. Must be unique within the\ \ agent and contain only letters, numbers, and underscores." example: get_customer_detail nodeType: type: string description: Type of the node example: extract_variables enum: - extract_variables edge: description: The next node to execute after the extract variables node completes. $ref: '#/components/schemas/Edge' parameters: $ref: '#/components/schemas/ExtractVariablesNodeParameters' description: Extracts and stores named variables from the conversation GlobalConditionNodeResponse: type: object properties: nodeId: type: string description: Unique identifier of the node. example: node_wcCIoGrJbw9AlXVk nodeName: type: string description: "Human-readable name of the node. Must be unique within the\ \ agent and contain only letters, numbers, and underscores." example: get_customer_detail nodeType: type: string description: Type of the node example: global_condition enum: - global_condition edge: description: The next node to execute after the global condition node completes. $ref: '#/components/schemas/ConditionEdge' description: Evaluates a global condition and routes the conversation to the configured destination node when the condition is met. IfElseNodeResponse: type: object properties: nodeId: type: string description: Unique identifier of the node. example: node_wcCIoGrJbw9AlXVk nodeName: type: string description: "Human-readable name of the node. Must be unique within the\ \ agent and contain only letters, numbers, and underscores." example: get_customer_detail nodeType: type: string description: Type of the node example: if_else enum: - if_else edges: type: array description: "The conditional branches evaluated by the node, each specifying\ \ a condition and its destination node. For the else branch, pass the\ \ condition as \"ELSE\"." items: $ref: '#/components/schemas/ConditionEdge' description: Evaluates conditions and routes the conversation to the next node based on the matching condition. Condition can be in natural language or it can be a javascript expression IntegrationToolNodeResponse: type: object properties: nodeId: type: string description: Unique identifier of the node. example: node_wcCIoGrJbw9AlXVk nodeName: type: string description: "Human-readable name of the node. Must be unique within the\ \ agent and contain only letters, numbers, and underscores." example: get_customer_detail nodeType: type: string description: Type of the node example: integration_tool enum: - integration_tool parameters: $ref: '#/components/schemas/IntegrationToolsNodeParameters' edge: description: The next node to execute after the integration tool node completes. $ref: '#/components/schemas/Edge' description: "Triggers an action from a connected app (e.g. Shopify, HubSpot)" IvrNavigatorNodeResponse: type: object properties: nodeId: type: string description: Unique identifier of the node. example: node_wcCIoGrJbw9AlXVk nodeName: type: string description: "Human-readable name of the node. Must be unique within the\ \ agent and contain only letters, numbers, and underscores." example: get_customer_detail nodeType: type: string description: Type of the node example: ivr_navigator enum: - ivr_navigator parameters: $ref: '#/components/schemas/IvrNavigatorNodeParameters' edge: description: The next node to execute after the IVR navigator node completes. $ref: '#/components/schemas/Edge' description: This is used to navigate through IVR. MessageNodeResponse: type: object properties: nodeId: type: string description: Unique identifier of the node. example: node_wcCIoGrJbw9AlXVk nodeName: type: string description: "Human-readable name of the node. Must be unique within the\ \ agent and contain only letters, numbers, and underscores." example: get_customer_detail nodeType: type: string description: Type of the node example: message enum: - message edge: description: The next node to execute after the message node completes. $ref: '#/components/schemas/Edge' parameters: $ref: '#/components/schemas/MessageNodeParameters' description: Sends a response to the user before continuing to the next node in the workflow. SubAgentNodeResponse: type: object properties: nodeId: type: string description: Unique identifier of the node. example: node_wcCIoGrJbw9AlXVk nodeName: type: string description: "Human-readable name of the node. Must be unique within the\ \ agent and contain only letters, numbers, and underscores." example: get_customer_detail nodeType: type: string description: "Type of the node, which determines its behavior and available\ \ configuration." example: sub_agent enum: - sub_agent parameters: $ref: '#/components/schemas/SubAgentNodeParameters' edges: type: array description: The exit conditions and destination nodes used to continue the workflow when the exit condition satisfies. items: $ref: '#/components/schemas/SubAgentEdge' tools: type: array description: Tools available to the sub-agent during execution. items: $ref: '#/components/schemas/CreateToolResponse' description: "Runs a sub-agent with its own instructions and tools, and continues\ \ the workflow based on its configured exit conditions." VoiceEndCallNodeResponse: type: object properties: nodeId: type: string description: Unique identifier of the node. example: node_wcCIoGrJbw9AlXVk nodeName: type: string description: "Human-readable name of the node. Must be unique within the\ \ agent and contain only letters, numbers, and underscores." example: get_customer_detail nodeType: type: string description: Type of the node example: voice_end_call enum: - voice_end_call edge: description: The next node to execute after the voice end call node completes. $ref: '#/components/schemas/Edge' description: Ends the current voice call VoiceTransferCallNodeResponse: type: object properties: nodeId: type: string description: Unique identifier of the node. example: node_wcCIoGrJbw9AlXVk nodeName: type: string description: "Human-readable name of the node. Must be unique within the\ \ agent and contain only letters, numbers, and underscores." example: get_customer_detail nodeType: type: string description: Type of the node example: voice_transfer_call enum: - voice_transfer_call parameters: $ref: '#/components/schemas/TransferCallNodeParameters' edge: description: The next node to execute after the voice transfer call node completes. $ref: '#/components/schemas/Edge' description: Transfers the active voice call to another number ConditionEdge: type: object properties: condition: type: string description: The condition that determines whether this branch should be selected. It can be natural language or a javascript expression. example: customer_type == 'premium' nextNodeId: type: string description: The unique identifier of the node to execute when the condition is satisfied. example: node_wcCIoGrJbw9AlXVk nextNodeName: type: string description: The name of the node to execute when the condition is satisfied. example: premium_customer description: The condition and destination node used to determine the next step in the workflow. Edge: type: object properties: nextNodeId: type: string description: The unique identifier of the node to execute next. example: node_wcCIoGrJbw9AlXVk nextNodeName: type: string description: The name of the node to execute next. example: get_customer_detail ExtractVariablesNodeParameters: type: object properties: variables: type: array description: List of variables to extract from the conversation items: $ref: '#/components/schemas/Variable' description: Configuration parameters defining the variables to extract from the conversation. IntegrationToolsNodeParameters: type: object properties: toolId: type: string description: The specific tool to execute example: tool_0QqvBhLiudhHyMDC speakWhileWaiting: type: boolean description: "If enabled, the agent will provide filler or holding speech\ \ while waiting for the tool to respond" example: true default: true placeholders: type: object additionalProperties: type: string description: "Defines values for the placeholders expected by the integration\ \ tool. Each key represents a placeholder name and its value can either\ \ be a static value or a dynamic variable using the format {{variable_name}}\ \ to inject runtime data." description: "Defines values for the placeholders expected by the integration\ \ tool. Each key represents a placeholder name and its value can either\ \ be a static value or a dynamic variable using the format {{variable_name}}\ \ to inject runtime data." mapVariables: type: object additionalProperties: type: string description: Maps the response paths of the tool to dynamic variables. Each key is the variable name and the value is the mapped response path description: Maps the response paths of the tool to dynamic variables. Each key is the variable name and the value is the mapped response path description: Configuration parameters that define the integration tool execution. IvrNavigatorNodeParameters: type: object properties: ivrStartsConversation: type: boolean description: Indicates whether the call is initiated by an IVR (Interactive Voice Response) system. Set to true when the interaction begins with an automated IVR prompt before connecting to an agent or system flow. example: true default: true pauseDelay: maximum: 30000 minimum: 500 type: integer description: Specifies the duration (in milliseconds) to wait before assuming the IVR system has finished its input or prompt. This delay helps ensure that subsequent actions are triggered only after the IVR interaction is complete. format: int64 example: 4000 default: 2000 description: Configuration parameters that control how the agent interacts with an IVR system. MessageNodeParameters: type: object properties: instructionsType: type: string description: "Specifies how the message instructions are defined, such as\ \ static text or dynamically generated instructions." example: static enum: - static - prompt instructions: type: string description: The instructions or message content to be delivered to the user. example: Hello! How can I help you today? description: Configuration parameters that define the message content and how its instructions are provided. SubAgentEdge: type: object properties: exitCondition: type: string description: The condition that determines when the sub-agent should exit and continue to the next node. It can be natural language or a javascript expression. example: customer is asking to cancel the order. nextNodeId: type: string description: The unique identifier of the node to execute after the sub-agent exits. example: node_wcCIoGrJbw9AlXVk nextNodeName: type: string description: The name of the node to execute after the sub-agent exits. example: cancel_order_sub_agent description: The exit conditions and destination nodes used to continue the workflow when the exit condition satisfies. SubAgentNodeParameters: type: object properties: instructions: type: string description: Instructions that define the behavior and objective of the sub-agent. description: Configuration parameters that define the behavior of the sub-agent. TransferCallNodeParameters: required: - transferTo type: object properties: transferToRouting: pattern: static|dynamic type: string description: "Defines how the destination for the call transfer is determined.\ \ Use 'static' to always transfer to a fixed phone number. Use 'dynamic'\ \ to determine the destination at runtime based on conditions or extracted\ \ variables (e.g., user intent such as OPD, radiology, etc.)." example: static enum: - static - dynamic default: static transferTo: type: string description: "Destination for the call transfer. If transferToRouting is\ \ 'static', provide a valid E.164 formatted phone number. If transferToRouting\ \ is 'dynamic', provide instructions or a dynamic variable placeholder\ \ to resolve the destination at runtime. For example: If the user wants\ \ to connect with OPD, transfer to {{dynamic_variable}} or a specific\ \ number. If the user wants to connect with radiology, transfer to {{dynamic_variable}}\ \ or a specific number." example: +9187788XXXXX extensionNumber: type: string description: Optional extension number to dial after the call is transferred. This is typically used in IVR systems to reach a specific department or user. example: "1234" transferSettings: $ref: '#/components/schemas/TransferSettings' description: Configuration parameters that define the destination and behavior of the call transfer. CreateAgentNodeRequest: required: - nodeType type: object properties: nodeName: maxLength: 128 minLength: 0 pattern: "^[a-zA-Z0-9_]+$" type: string description: "Human-readable name of the node. Must be unique within the\ \ agent and contain only letters, numbers, and underscores." example: get_customer_detail nodeType: type: string description: "Type of the node, which determines its behavior and available\ \ configuration." discriminator: propertyName: nodeType oneOf: - $ref: '#/components/schemas/MessageNodeRequest' - $ref: '#/components/schemas/SubAgentNodeRequest' - $ref: '#/components/schemas/IfElseNodeRequest' - $ref: '#/components/schemas/GlobalConditionNodeRequest' - $ref: '#/components/schemas/VoiceTransferCallNodeRequest' - $ref: '#/components/schemas/ExtractVariablesNodeRequest' - $ref: '#/components/schemas/IvrNavigatorNodeRequest' - $ref: '#/components/schemas/VoiceEndCallNodeRequest' - $ref: '#/components/schemas/IntegrationToolNodeRequest' CreateConversationalAgentRequest: type: object properties: agentName: maxLength: 128 minLength: 0 type: string description: Human-readable name of the agent used to identify it in the dashboard and APIs. example: Auralis startNodeName: maxLength: 128 minLength: 0 pattern: "^[a-zA-Z0-9_]+$" type: string description: "The name of the node where the agent workflow starts. Must\ \ contain only letters, numbers, and underscores." example: Welcome agentSettings: $ref: '#/components/schemas/CreateAgentSettingsRequest' nodes: type: array description: The list of nodes that define the agent's conversational workflow. items: $ref: '#/components/schemas/CreateAgentNodeRequest' ExtractVariablesNodeRequest: type: object description: Extracts and stores named variables from the conversation allOf: - $ref: '#/components/schemas/CreateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: extract_variables enum: - extract_variables edge: description: The next node to execute after the extract variables node completes. $ref: '#/components/schemas/Edge' parameters: $ref: '#/components/schemas/ExtractVariablesNodeParameters' GlobalConditionNodeRequest: type: object description: Evaluates a global condition and routes the conversation to the configured destination node when the condition is met. allOf: - $ref: '#/components/schemas/CreateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: global_condition enum: - global_condition edge: $ref: '#/components/schemas/ConditionEdge' IfElseNodeRequest: type: object description: Evaluates conditions and routes the conversation to the next node based on the matching condition. Condition can be in natural language or it can be a javascript expression allOf: - $ref: '#/components/schemas/CreateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: if_else enum: - if_else edges: type: array description: "The conditional branches evaluated by the node, each specifying\ \ a condition and its destination node. For the else branch, pass the\ \ condition as \"ELSE\"." items: $ref: '#/components/schemas/ConditionEdge' IntegrationToolNodeRequest: type: object description: "Triggers an action from a connected app (e.g. Shopify, HubSpot)" allOf: - $ref: '#/components/schemas/CreateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: integration_tool enum: - integration_tool parameters: $ref: '#/components/schemas/IntegrationToolsNodeParameters' edge: description: The next node to execute after the integration tool node completes. $ref: '#/components/schemas/Edge' IvrNavigatorNodeRequest: type: object description: This is used to navigate through IVR. allOf: - $ref: '#/components/schemas/CreateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: ivr_navigator enum: - ivr_navigator parameters: $ref: '#/components/schemas/IvrNavigatorNodeParameters' edge: description: The next node to execute after the IVR navigator node completes. $ref: '#/components/schemas/Edge' MessageNodeRequest: type: object description: Sends a response to the user before continuing to the next node in the workflow. allOf: - $ref: '#/components/schemas/CreateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: message enum: - message edge: description: The next node to execute after the message node completes. $ref: '#/components/schemas/Edge' parameters: $ref: '#/components/schemas/MessageNodeParameters' SubAgentNodeRequest: type: object description: "Runs a sub-agent with its own instructions and tools, and continues\ \ the workflow based on its configured exit conditions." allOf: - $ref: '#/components/schemas/CreateAgentNodeRequest' - type: object properties: nodeType: type: string description: "Type of the node, which determines its behavior and available\ \ configuration." example: sub_agent enum: - sub_agent parameters: $ref: '#/components/schemas/SubAgentNodeParameters' edges: type: array description: The exit conditions and destination nodes used to continue the workflow when the exit condition satisfies. items: $ref: '#/components/schemas/SubAgentEdge' tools: type: array description: Tools available to the sub-agent during execution. items: $ref: '#/components/schemas/CreateToolRequest' VoiceEndCallNodeRequest: type: object description: Ends the current voice call allOf: - $ref: '#/components/schemas/CreateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: voice_end_call enum: - voice_end_call edge: description: The next node to execute after the voice end call node completes. $ref: '#/components/schemas/Edge' VoiceTransferCallNodeRequest: type: object description: Transfers the active voice call to another number allOf: - $ref: '#/components/schemas/CreateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: voice_transfer_call enum: - voice_transfer_call parameters: $ref: '#/components/schemas/TransferCallNodeParameters' edge: description: The next node to execute after the voice transfer call node completes. $ref: '#/components/schemas/Edge' UpdateAgentNodeRequest: required: - nodeType type: object properties: nodeId: type: string description: "The unique identifier of an existing node within the agent.\ \ If provided, the corresponding node will be updated. If omitted, a new\ \ node will be created and added to the agent." example: node_wcCIoGrJbw9AlXVk nodeName: maxLength: 128 minLength: 0 pattern: "^[a-zA-Z0-9_]+$" type: string description: "Human-readable name of the node. Must be unique within the\ \ agent and contain only letters, numbers, and underscores." example: get_customer_detail nodeType: type: string description: "Type of the node, which determines its behavior and available\ \ configuration." discriminator: propertyName: nodeType oneOf: - $ref: '#/components/schemas/UpdateMessageNodeRequest' - $ref: '#/components/schemas/UpdateSubAgentNodeRequest' - $ref: '#/components/schemas/UpdateIfElseNodeRequest' - $ref: '#/components/schemas/UpdateGlobalConditionNodeRequest' - $ref: '#/components/schemas/UpdateVoiceTransferCallNodeRequest' - $ref: '#/components/schemas/UpdateExtractVariablesNodeRequest' - $ref: '#/components/schemas/UpdateIvrNavigatorNodeRequest' - $ref: '#/components/schemas/UpdateVoiceEndCallNodeRequest' - $ref: '#/components/schemas/UpdateIntegrationToolNodeRequest' UpdateExtractVariablesNodeRequest: type: object description: Extracts and stores named variables from the conversation allOf: - $ref: '#/components/schemas/UpdateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: extract_variables enum: - extract_variables edge: description: The next node to execute after the extract variables node completes. $ref: '#/components/schemas/Edge' parameters: $ref: '#/components/schemas/ExtractVariablesNodeParameters' UpdateGlobalConditionNodeRequest: type: object description: Evaluates a global condition and routes the conversation to the configured destination node when the condition is met. allOf: - $ref: '#/components/schemas/UpdateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: global_condition enum: - global_condition edge: description: The next node to execute after the global condition node completes. $ref: '#/components/schemas/ConditionEdge' UpdateIfElseNodeRequest: type: object description: Evaluates conditions and routes the conversation to the next node based on the matching condition. Condition can be in natural language or it can be a javascript expression allOf: - $ref: '#/components/schemas/UpdateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: if_else enum: - if_else edges: type: array description: "The conditional branches evaluated by the node, each specifying\ \ a condition and its destination node. For the else branch, pass the\ \ condition as \"ELSE\"." items: $ref: '#/components/schemas/ConditionEdge' UpdateIntegrationToolNodeRequest: type: object description: "Triggers an action from a connected app (e.g. Shopify, HubSpot)" allOf: - $ref: '#/components/schemas/UpdateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: integration_tool enum: - integration_tool parameters: $ref: '#/components/schemas/IntegrationToolsNodeParameters' edge: description: The next node to execute after the integration tool node completes. $ref: '#/components/schemas/Edge' UpdateIvrNavigatorNodeRequest: type: object description: This is used to navigate through IVR. allOf: - $ref: '#/components/schemas/UpdateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: ivr_navigator enum: - ivr_navigator parameters: $ref: '#/components/schemas/IvrNavigatorNodeParameters' edge: description: The next node to execute after the IVR navigator node completes. $ref: '#/components/schemas/Edge' UpdateMessageNodeRequest: type: object description: Sends a response to the user before continuing to the next node in the workflow. allOf: - $ref: '#/components/schemas/UpdateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: message enum: - message edge: description: The next node to execute after the message node completes. $ref: '#/components/schemas/Edge' parameters: $ref: '#/components/schemas/MessageNodeParameters' UpdateSubAgentNodeRequest: type: object description: "Runs a sub-agent with its own instructions and tools, and continues\ \ the workflow based on its configured exit conditions." allOf: - $ref: '#/components/schemas/UpdateAgentNodeRequest' - type: object properties: nodeType: type: string description: "Type of the node, which determines its behavior and available\ \ configuration." example: sub_agent enum: - sub_agent parameters: $ref: '#/components/schemas/SubAgentNodeParameters' edges: type: array description: The exit conditions and destination nodes used to continue the workflow when the exit condition satisfies. items: $ref: '#/components/schemas/SubAgentEdge' tools: type: array description: "The complete list of tools available to the sub-agent during\ \ execution. This list replaces the sub-agent's existing tools, and\ \ any existing tool omitted from the list is deleted. Pass an empty\ \ array ([]) to delete all tools. Pass null to leave the existing tools\ \ unchanged." items: $ref: '#/components/schemas/CreateToolRequest' UpdateVoiceEndCallNodeRequest: type: object description: Ends the current voice call allOf: - $ref: '#/components/schemas/UpdateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: voice_end_call enum: - voice_end_call edge: description: The next node to execute after the voice end call node completes. $ref: '#/components/schemas/Edge' UpdateVoiceTransferCallNodeRequest: type: object description: Transfers the active voice call to another number allOf: - $ref: '#/components/schemas/UpdateAgentNodeRequest' - type: object properties: nodeType: type: string description: Type of the node example: voice_transfer_call enum: - voice_transfer_call parameters: $ref: '#/components/schemas/TransferCallNodeParameters' edge: description: The next node to execute after the voice transfer call node completes. $ref: '#/components/schemas/Edge' UpdateConversationalAgentRequest: type: object properties: agentName: maxLength: 128 minLength: 0 type: string description: Human-readable name of the agent used to identify it in the dashboard and APIs. example: Auralis startNodeName: maxLength: 128 minLength: 0 pattern: "^[a-zA-Z0-9_]+$" type: string description: "The name of the node where the agent workflow starts. Must\ \ contain only letters, numbers, and underscores." example: Welcome agentSettings: $ref: '#/components/schemas/UpdateAgentSettingsRequest' nodes: type: array description: "The complete list of nodes that define the agent's conversational\ \ workflow. This list replaces the agent's existing nodes: nodes with\ \ a nodeId are updated, nodes without a nodeId are created, and any existing\ \ node omitted from the list is deleted." items: $ref: '#/components/schemas/UpdateAgentNodeRequest' description: "Request body for updating an existing conversational agent, including\ \ its start node, runtime settings, and workflow nodes." # Campaign APIs Schemas CreateCampaignRequest: required: - agentId - campaignName - file - sipPhoneNumber type: object properties: campaignName: maxLength: 128 minLength: 1 type: string description: "Display name for this campaign. Used to identify the campaign\ \ in listings, dashboards, and reports. Must be unique within your account." example: Q4 Outreach Campaign sipPhoneNumber: pattern: "^\\+[1-9][0-9]{6,14}$" type: string description: "Caller ID phone number used for all outbound calls in this\ \ campaign, in +E.164 format. Must be a number provisioned in SigmaMind\ \ or configured via SIP trunking that is enabled for outbound calls. This\ \ number appears on the recipient's device as the incoming caller." example: "+14155552671" agentId: maxLength: 64 minLength: 1 type: string description: "Unique identifier of the agent that will handle every call\ \ in this campaign. The agent controls the conversation flow, scripts,\ \ and tools used during each call. All contacts in the uploaded CSV will\ \ be called using this agent." example: agent_D5D0p7TUs66TTAEAx file: type: string format: binary isScheduled: type: boolean description: "Whether this campaign should be held and launched at a future\ \ date and time instead of starting immediately. When true, scheduledDate,\ \ scheduledTime, and scheduledTimezone are all required. When false or\ \ omitted, the campaign starts as soon as it is created." example: true scheduledDate: type: string description: "Date on which the campaign should launch, in YYYY-MM-DD format.\ \ Required when isScheduled is true. Ignored when isScheduled is false\ \ or omitted. Must be a future date." format: date example: 2025-09-25 scheduledTime: type: string description: "Time at which the campaign should launch on the scheduled\ \ date, in HH:mm:ss format. Required when isScheduled is true. Ignored\ \ when isScheduled is false or omitted. Interpreted in the timezone specified\ \ by scheduledTimezone." format: time example: 12:00:00 scheduledTimezone: type: string description: "IANA timezone name used to interpret scheduledDate and scheduledTime.\ \ Required when isScheduled is true. Ignored when isScheduled is false\ \ or omitted. Use a valid IANA timezone identifier (e.g., 'America/Los_Angeles',\ \ 'Europe/London', 'Asia/Kolkata')." example: America/Los_Angeles concurrentCalls: type: integer description: "Maximum number of calls the campaign is allowed to have active\ \ simultaneously. Controls the dialling throughput — a higher value dials\ \ more contacts in parallel. If omitted, the account default is used.\ \ Must be a positive integer." format: int32 example: 5 dynamicVariables: type: object description: Default dynamic variable values applied to every call in the campaign when the CSV does not supply a value for a given variable. Keys must match variable names defined in the agent's configuration. Per-contact values in the CSV take precedence over these defaults. Leave empty if the CSV provides all required variables. example: customer_name: Michael additionalProperties: oneOf: - type: string - type: number - type: boolean - type: object - type: array description: Request body to create a new outbound call campaign. A campaign dials a list of phone numbers using a selected agent and caller number. The contact list and any per-contact dynamic variables are uploaded as a CSV file. Campaigns can start immediately or be scheduled for a future date and time. CampaignResponse: type: object properties: campaignId: type: string description: "Unique identifier for this campaign. Use this value as campaignId\ \ when updating, deleting, or triggering this campaign via the API." example: camp_XiQEBcj9cc5TFRB4 campaignName: type: string description: Display name of this campaign as set at creation time. Used to identify the campaign in listings and dashboards. example: Q4 Outreach Campaign campaignStatus: type: string description: Current lifecycle state of the campaign. 'live' means the campaign is actively dialling contacts. 'scheduled' means the campaign is configured to launch at a future date and time. 'paused' means dialling has been suspended and can be resumed. 'completed' means all contacts have been dialled and the campaign has finished. example: live enum: - live - scheduled - paused - completed scheduledDate: type: string description: "The date and time when this campaign is scheduled to launch,\ \ including timezone. Present only when isScheduled is true. Null for\ \ campaigns that started immediately at creation." format: date-time example: 2025-09-25T12:00:00-07:00 concurrentCalls: type: integer description: Maximum number of calls allowed to be active simultaneously in this campaign. Determines dialling throughput — higher values dial more contacts in parallel. Reflects the value set at creation or last updated via the update endpoint. format: int32 example: 5 agent: $ref: '#/components/schemas/AgentResponse' phoneNumber: $ref: '#/components/schemas/PhoneNumberResponse' errors: type: array description: List of validation errors encountered when processing the campaign's contact CSV file. Present only when the upload contained rows with invalid phone numbers or missing required variables. Null or empty when the file was processed without errors. example: - "Row 3: missing required variable 'customer_name'" - "Row 7: invalid phone number '+1234'" items: type: string description: List of validation errors encountered when processing the campaign's contact CSV file. Present only when the upload contained rows with invalid phone numbers or missing required variables. Null or empty when the file was processed without errors. example: "[\"Row 3: missing required variable 'customer_name'\",\"Row\ \ 7: invalid phone number '+1234'\"]" scheduled: type: boolean description: "Full details of a campaign record. Includes the campaign's identity,\ \ current status, schedule configuration, the agent handling calls, and the\ \ caller phone number used to dial contacts." UpdateCampaignRequest: type: object properties: campaignName: maxLength: 128 minLength: 1 type: string description: "Display name for this campaign. Used to identify the campaign\ \ in listings, dashboards, and reports. Must be unique within your account." example: Q4 Outreach Campaign sipPhoneNumber: pattern: "^\\+[1-9][0-9]{6,14}$" type: string description: "Caller ID phone number used for all outbound calls in this\ \ campaign, in +E.164 format. Must be a number provisioned in SigmaMind\ \ or configured via SIP trunking that is enabled for outbound calls. This\ \ number appears on the recipient's device as the incoming caller." example: "+14155552671" agentId: maxLength: 64 minLength: 1 type: string description: "Unique identifier of the agent that will handle every call\ \ in this campaign. The agent controls the conversation flow, scripts,\ \ and tools used during each call. All contacts in the uploaded CSV will\ \ be called using this agent." example: agent_D5D0p7TUs66TTAEAx isScheduled: type: boolean description: "Whether this campaign should be held and launched at a future\ \ date and time instead of starting immediately. When true, scheduledDate,\ \ scheduledTime, and scheduledTimezone are all required. When false or\ \ omitted, the campaign starts as soon as it is created." example: true scheduledDate: type: string description: "Date on which the campaign should launch, in YYYY-MM-DD format.\ \ Required when isScheduled is true. Ignored when isScheduled is false\ \ or omitted. Must be a future date." format: date example: 2025-09-25 scheduledTime: type: string description: "Time at which the campaign should launch on the scheduled\ \ date, in HH:mm:ss format. Required when isScheduled is true. Ignored\ \ when isScheduled is false or omitted. Interpreted in the timezone specified\ \ by scheduledTimezone." format: time example: 12:00:00 scheduledTimezone: type: string description: "IANA timezone name used to interpret scheduledDate and scheduledTime.\ \ Required when isScheduled is true. Ignored when isScheduled is false\ \ or omitted. Use a valid IANA timezone identifier (e.g., 'America/Los_Angeles',\ \ 'Europe/London', 'Asia/Kolkata')." example: America/Los_Angeles concurrentCalls: type: integer description: "Maximum number of calls the campaign is allowed to have active\ \ simultaneously. Controls the dialling throughput — a higher value dials\ \ more contacts in parallel. If omitted, the account default is used.\ \ Must be a positive integer." format: int32 example: 5 dynamicVariables: type: object description: Default dynamic variable values applied to every call in the campaign when the CSV does not supply a value for a given variable. Keys must match variable names defined in the agent's configuration. Per-contact values in the CSV take precedence over these defaults. Leave empty if the CSV provides all required variables. example: customer_name: Michael additionalProperties: oneOf: - type: string - type: number - type: boolean - type: object - type: array description: Request body to update a campaign. A campaign dials a list of phone numbers using a selected agent and caller number. The contact list and any per-contact dynamic variables are uploaded as a CSV file. Campaigns can start immediately or be scheduled for a future date and time. PaginatedResponseCampaignResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/CampaignResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # Integrations APIs Schemas CreateIntegrationRequest: required: - name type: object properties: name: maxLength: 128 minLength: 0 type: string description: Human-readable label for this integration example: Shopify description: maxLength: 512 minLength: 0 type: string description: Optional description of what this integration is used for example: Handles order lookups for the support agent UpdateIntegrationRequest: type: object properties: name: maxLength: 128 minLength: 0 type: string description: Human-readable label for this integration example: my_shopify_store description: maxLength: 512 minLength: 0 type: string description: Optional description of what this integration is used for example: Handles order lookups and refunds for the support agent IntegrationResponse: type: object properties: integrationId: type: string description: "Unique identifier for this integration. Pass this value as\ \ integrationId when executing tools, \nupdating this integration, or\ \ managing its auth configuration." example: intg_AuUKK371Spr5 name: type: string description: "Human-readable name of the integration. Helps identify the\ \ connected system (e.g., Shopify store, CRM, payment provider)." example: My Shopify Store description: type: string description: Optional explanation of what this integration is used for. Useful for agents to determine when this integration should be selected. example: Handles order lookups and customer data retrieval authentication: $ref: '#/components/schemas/IntegrationAuthResponse' tools: type: array description: "Catalog of executable operations available via this integration.\ \ Each tool represents a specific \nAPI capability (e.g., fetch order,\ \ create customer). To perform an action: inspect each tool's \nname and\ \ description, select the one matching the task, then invoke it using\ \ its toolId. \nAn empty list means no tools have been configured yet." items: $ref: '#/components/schemas/IntegrationToolResponse' createdAt: type: string description: Timestamp when the integration was created (in UTC). Primarily for auditing and tracking purposes. format: date-time example: 2024-04-20T10:00:00Z updatedAt: type: string description: Timestamp when the integration was last updated (in UTC). Indicates the most recent configuration change. format: date-time example: 2024-04-21T08:30:00Z description: "Represents a fully configured third-party integration. Includes\ \ its identity, authentication configuration, and available tools. Use this\ \ response to understand how to invoke external APIs via this integration.\ \ Authentication and headers are automatically applied when tools under this\ \ integration are executed." PaginatedResponseIntegrationResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/IntegrationResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # Integration Auth APIs Schemas CreateIntegrationAuthRequest: required: - authType type: object properties: authType: type: string description: "Specifies the authentication method used for outgoing requests.\ \ Choose based on how the target API expects credentials: API_KEY → when\ \ a key must be sent via header or query parameter. BEARER_TOKEN → when\ \ a token is sent in the Authorization header. BASIC_AUTH → when username/password\ \ is required. NO_AUTH → when no authentication is needed. This field\ \ determines which other fields must be provided." example: API_KEY enum: - NO_AUTH - BASIC_AUTH - BEARER_TOKEN - API_KEY token: type: string description: "Access token used for Bearer authentication. Required only\ \ when authType is BEARER_TOKEN. Automatically added to requests as: Authorization:\ \ Bearer ." example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... username: maxLength: 256 minLength: 0 type: string description: Username used for Basic authentication. Required only when authType is BASIC_AUTH. Combined with password and encoded into the Authorization header. example: api_user@example.com password: type: string description: Password used for Basic authentication. Required only when authType is BASIC_AUTH. Combined with username and encoded into the Authorization header. example: s3cretP@ssword apiKey: $ref: '#/components/schemas/ApiKeyRequest' headers: type: array description: Optional static headers that will be included in every outgoing request. Useful for fixed metadata or required headers that do not change per request. These are applied in addition to authentication headers. example: - key: X-Request-Source value: sigmamind items: $ref: '#/components/schemas/HeaderEntry' description: Defines authentication credentials for a third-party integration. Use this to tell the system how to authenticate outbound API requests. Select an authType and provide only the fields required for that type. All other fields will be ignored. This configuration is applied automatically to every request made using this integration. UpdateIntegrationAuthRequest: type: object properties: token: type: string description: Replacement bearer token. Applicable only when the auth record was originally created with authType BEARER_TOKEN. Overwrites the previously stored token. The system will use this new value on all subsequent outbound requests. Omit this field to leave the existing token unchanged. example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...updated username: maxLength: 256 minLength: 0 type: string description: Replacement username for Basic authentication. Applicable only when the auth record was originally created with authType BASIC_AUTH. Can be updated independently — omitting this field leaves the existing username unchanged. example: new_api_user@example.com password: maxLength: 512 minLength: 0 type: string description: Replacement password for Basic authentication. Applicable only when the auth record was originally created with authType BASIC_AUTH. Can be updated independently — omitting this field leaves the existing password unchanged. example: newS3cretP@ssword apiKey: $ref: '#/components/schemas/ApiKeyRequest' headers: type: array description: "Replacement list of static headers attached to every outbound\ \ request for this auth record. Pass a non-empty list to overwrite all\ \ existing headers with the new set. Pass an empty list [] to remove all\ \ headers. Omit this field entirely to leave existing headers unchanged." items: $ref: '#/components/schemas/HeaderEntry' description: Request body to partially update an existing authentication credential record. Only fields included in the request body are updated — omitted fields are left unchanged. The authType set at creation time is permanent and cannot be changed via this endpoint. Provide only the credential fields that match the original authType. IntegrationAuthResponse: type: object properties: authId: type: string description: Unique identifier for the auth record example: auth_P3kNz7Yv1Qm9 integrationId: type: string description: Unique identifier of the parent integration example: intg_AuUKK371Spr5 authType: type: string description: "The authentication strategy this credential set uses. Determines\ \ which credential fields are required: API_KEY — provide the apiKey object\ \ (key name, secret value, and position). BEARER_TOKEN — provide the token\ \ field. BASIC_AUTH — provide username and password fields. NO_AUTH —\ \ no credential fields required." example: API_KEY enum: - NO_AUTH - BASIC_AUTH - BEARER_TOKEN - API_KEY headers: type: object description: Optional list of static HTTP headers attached to every outbound request under this auth. Applied on top of any headers defined at the integration or tool level. Useful for fixed metadata headers required by the third-party API. example: - key: X-Request-Source value: sigmamind createdAt: type: string description: Timestamp when the record was created format: date-time updatedAt: type: string description: Timestamp when the record was last updated format: date-time ApiKeyRequest: required: - key - position - value type: object properties: key: maxLength: 128 minLength: 0 type: string description: Name of the header or query parameter that carries the API key. Must match what the target API expects. example: X-Shopify-Access-Token value: type: string description: The API key or secret value sent with each request. example: shpat_abc123xyz456 position: type: string description: Where the API key should be added in the request. header → sent as an HTTP header (most common). query → appended to the request URL. example: header default: header enum: - header - query description: Defines how an API key is attached to outgoing requests. Use this when the API requires a key in headers or query parameters. example: key: X-API-KEY value: position: header HeaderEntry: required: - key - value type: object properties: key: maxLength: 256 minLength: 0 type: string description: HTTP header name exactly as expected by the target API. example: Content-Type value: maxLength: 1024 minLength: 0 type: string description: Static value for this header sent with every request. Must be a fixed string — use queryParams or bodyParams for dynamic values. example: application/json description: A single static HTTP header included in every request made by this tool. Tool-level headers are merged with integration-level and auth-level headers; tool-level values take precedence on key conflicts. example: - key: Content-Type value: application/json QueryParam: required: - key type: object properties: key: maxLength: 128 minLength: 0 type: string description: Query parameter name as expected by the target API. example: status value: maxLength: 1024 minLength: 0 type: string description: "Value for this query parameter. Use a {{variable}} placeholder\ \ for values the agent supplies at runtime. Static string values are also\ \ accepted for fixed parameters." example: "{{status}}" description: "A single query string parameter appended to the request URL at\ \ invocation time. Use {{variable}} placeholders in values for parameters\ \ the agent supplies dynamically. Path variables embedded in the endpoint\ \ URL using {{variable}} syntax are separate and do not need to be declared\ \ here." example: - key: status value: "{{status}}" PaginatedResponseIntegrationAuthResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/IntegrationAuthResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # Integration Tools APIs Schemas CreateIntegrationToolRequest: required: - description - method - name - url type: object properties: name: maxLength: 128 minLength: 0 type: string description: "Action-oriented, snake_case name that uniquely identifies\ \ this tool within the integration. AI agents use this name to select\ \ the correct tool when deciding which operation to invoke. Must be unique\ \ within the integration. Good examples: 'get_customer', 'create_order',\ \ 'cancel_subscription'." example: get_customer description: maxLength: 1024 minLength: 0 type: string description: "Explanation of what this tool does and the exact conditions\ \ under which an AI agent should invoke it. Agents rely on this description\ \ to match a task to the correct tool — be specific about the action,\ \ the resource it operates on, and any inputs the agent must supply." example: "Fetches a Shopify customer record by customer ID. Call this tool\ \ when you need to look up customer details such as name, email, or order\ \ history." method: type: string description: HTTP method used when invoking this tool's endpoint. GET retrieves a resource without side effects. POST creates a new resource. PUT fully replaces an existing resource. PATCH partially updates an existing resource. DELETE removes a resource. example: GET enum: - GET - POST - PUT - PATCH - DELETE url: maxLength: 1024 minLength: 0 type: string description: "Full URL of the API endpoint this tool calls. Supports {{variable}}\ \ placeholders for path segments the agent resolves at runtime (e.g.,\ \ {{customerId}} in the path). Path variables embedded here do not need\ \ to be redeclared in queryParams." example: "https://my-store.myshopify.com/admin/api/2024-01/customers/{{customerId}}.json" headers: type: array description: "Static HTTP headers sent on every request made by this tool.\ \ Merged with headers defined at the integration and auth levels; tool-level\ \ headers take precedence on key conflicts. Values may contain {{variable}}\ \ placeholders resolved by the agent at runtime. Leave empty if no tool-specific\ \ headers are needed." example: - key: Content-Type value: application/json items: $ref: '#/components/schemas/HeaderEntry' queryParams: type: array description: "Query string parameters appended to the URL on every invocation\ \ (e.g., ?status=active&limit=10). Values support {{variable}} placeholders\ \ so the agent can supply them at runtime. Path variables already embedded\ \ in the URL using {{variable}} syntax do not need to be listed here." example: - key: status value: "{{status}}" items: $ref: '#/components/schemas/QueryParam' bodyParams: type: object description: "Request body payload sent when this tool is invoked, as a\ \ JSON object. Values support {{variable}} placeholders that the agent\ \ resolves at runtime. Provide only for POST, PUT, and PATCH tools. Leave\ \ empty or omit for GET and DELETE — body content is ignored for those\ \ methods." example: first_name: "{{firstName}}" email: "{{email}}" additionalProperties: oneOf: - type: string - type: number - type: boolean - type: object - type: array description: "Request body to create a new API tool under an integration. A\ \ tool represents a single callable API operation — for example 'get_customer'\ \ or 'create_order' — that an AI agent can invoke at runtime. Dynamic values\ \ are declared using {{variable}} placeholders in the URL, headers, query\ \ params, or body; the agent resolves these at invocation time." UpdateIntegrationToolRequest: type: object properties: name: maxLength: 128 minLength: 0 type: string description: Replacement tool name. Must be snake_case and action-oriented. AI agents use this name to identify and select the correct tool when deciding which operation to invoke. Must remain unique within the integration. Omit to leave the existing name unchanged. example: get_customer_with_orders description: maxLength: 1024 minLength: 0 type: string description: "Replacement description of what this tool does and when an\ \ agent should invoke it. Agents rely on this to match a task to the correct\ \ tool — be specific about the action, the resource it operates on, and\ \ required inputs. Omit to leave the existing description unchanged." example: Fetches a Shopify customer including their recent orders. Use when full customer context including purchase history is needed. accessType: type: string description: Visibility scope of this tool. 'local' means the tool is private to your account and only accessible within your integrations. 'community' means the tool is shared and discoverable by other accounts. Omit to leave the existing scope unchanged. Corresponds to the 'scope' field returned in IntegrationToolResponse. example: local enum: - local - community method: type: string description: Replacement HTTP method for the underlying API call. GET retrieves a resource without side effects. POST creates a new resource. PUT fully replaces an existing resource. PATCH partially updates an existing resource. DELETE removes a resource. Omit to leave the existing method unchanged. example: GET enum: - GET - POST - PUT - PATCH - DELETE endpoint: maxLength: 1024 minLength: 0 type: string description: "Replacement full URL of the API endpoint this tool calls.\ \ Supports {{variable}} placeholders for path segments the agent resolves\ \ at runtime. Updating this field automatically re-extracts all {{variable}}\ \ placeholders and refreshes the tool's variable list. Omit to leave the\ \ existing endpoint unchanged." example: "https://my-store.myshopify.com/admin/api/2024-01/customers/{{customerId}}/orders.json" headers: type: array description: "Replacement list of static HTTP headers sent on every request\ \ by this tool. Tool-level headers are merged with integration and auth-level\ \ headers; tool-level values take precedence on key conflicts. Pass a\ \ non-empty list to overwrite all existing headers. Pass an empty list\ \ [] to remove all tool-level headers. Omit this field entirely to leave\ \ existing headers unchanged." example: - key: Content-Type value: application/json items: $ref: '#/components/schemas/HeaderEntry' queryParams: type: array description: "Replacement list of query string parameters appended to the\ \ URL on every invocation. Values support {{variable}} placeholders the\ \ agent resolves at runtime. Path variables embedded in the endpoint URL\ \ using {{variable}} syntax do not need to be listed here. Pass a non-empty\ \ list to overwrite all existing query params. Pass an empty list [] to\ \ remove all query params. Omit this field entirely to leave existing\ \ query params unchanged. Updating this field triggers automatic re-extraction\ \ of {{variable}} placeholders." example: - key: status value: "{{status}}" items: $ref: '#/components/schemas/QueryParam' bodyParams: type: object description: "Replacement request body payload, as a JSON object. Values\ \ support {{variable}} placeholders the agent resolves at runtime. Pass\ \ a non-null map to overwrite the entire existing body. To remove the\ \ body entirely, pass an empty map {}. Omit this field (leave it null)\ \ to leave the existing body unchanged. Applicable only for POST, PUT,\ \ and PATCH tools — ignored for GET and DELETE. Updating this field triggers\ \ automatic re-extraction of {{variable}} placeholders." example: first_name: "{{firstName}}" email: "{{email}}" description: "Request body to partially update an existing integration tool.\ \ Only fields included in the request are updated — omitted fields remain\ \ unchanged. Updating endpoint, queryParams, or bodyParams automatically re-extracts\ \ all {{variable}} placeholders and refreshes the tool's variable list." IntegrationToolResponse: type: object properties: toolId: type: string description: "Unique identifier for this tool. Use this value as toolId\ \ when executing, updating, or deleting this tool." example: tool_X9pLm2Wq8Rt3 integrationId: type: string description: Unique identifier of the integration this tool belongs to. Use this value as integrationId when making requests scoped to the parent integration. example: intg_AuUKK371Spr5 name: type: string description: "Action-oriented name for this tool that identifies the operation\ \ it performs. AI agents use this name to match a task to the correct\ \ tool. Follows snake_case convention (e.g., 'get_customer', 'create_order')." example: get_order_details description: type: string description: "Explanation of what this tool does and when an AI agent should\ \ invoke it. Agents rely on this description to decide whether this tool\ \ matches the current task. A good description names the action, the resource\ \ it operates on, and required inputs." example: "Fetches order details from Shopify by order ID. Call this tool\ \ when you need to retrieve order status, line items, or shipping info." method: type: string description: HTTP method used when invoking this tool's endpoint. GET retrieves a resource without side effects. POST creates a new resource. PUT fully replaces an existing resource. PATCH partially updates an existing resource. DELETE removes a resource. example: GET enum: - GET - POST - PUT - PATCH - DELETE url: type: string description: "Full URL of the API endpoint this tool calls, including any\ \ {{variable}} placeholders that the agent resolves at runtime using the\ \ declared parameters. Path segments wrapped in {{}} (e.g., {{orderId}})\ \ are substituted before the request is sent." example: "https://my-store.myshopify.com/admin/api/2024-01/orders/{{orderId}}.json" scope: type: string description: Visibility scope of this tool. 'local' means the tool is private to your account and only accessible within your integrations. 'community' means the tool is shared and discoverable by other users. example: local enum: - local - community headers: $ref: '#/components/schemas/JsonNode' queryParams: $ref: '#/components/schemas/JsonNode' bodyParams: $ref: '#/components/schemas/JsonNode' createdAt: type: string description: "UTC timestamp when this tool was created, in ISO 8601 format.\ \ Use for auditing or determining how long the tool has been active." format: date-time example: 2024-04-20T10:00:00Z updatedAt: type: string description: "UTC timestamp when this tool was last modified, in ISO 8601\ \ format. Use to detect configuration changes or invalidate cached tool\ \ definitions." format: date-time example: 2024-04-21T08:30:00Z description: "Represents a single callable API tool registered under an integration.\ \ Each tool maps to one specific API operation (e.g., 'Get Order', 'Create\ \ Customer') and carries its full invocation config: HTTP method, endpoint\ \ URL, headers, and parameters. AI agents use this response to understand\ \ what the tool does and how to invoke it." ExecuteToolRequest: type: object properties: placeholders: type: object additionalProperties: type: string description: "A map of placeholder names to values used to resolve {{placeholder}}\ \ tokens in the tool's endpoint URL, query parameters, and request body\ \ at runtime. Each placeholder used in the request must have a corresponding\ \ entry in this map. Example: for endpoint '/customers/{{customerId}}.json',\ \ provide {\"customerId\": \"7654321\"}." example: "{\"customerId\":\"7654321\"}" description: "A map of placeholder names to values used to resolve {{placeholder}}\ \ tokens in the tool's endpoint URL, query parameters, and request body\ \ at runtime. Each placeholder used in the request must have a corresponding\ \ entry in this map. Example: for endpoint '/customers/{{customerId}}.json',\ \ provide {\"customerId\": \"7654321\"}." example: customerId: "7654321" authId: maxLength: 64 minLength: 0 type: string description: 'The authId of the credential set to use for this execution. ' example: auth_P3kNz7Yv1Qm9 saveAsMock: $ref: '#/components/schemas/SaveAsMockRequest' description: "Request body to execute a tool against its configured third-party\ \ API. Supply values for every {{variable}} placeholder declared in the tool's\ \ endpoint, queryParams, and bodyParams. The tool's stored auth credentials\ \ are resolved automatically — you do not need to pass credentials here." ExecuteToolResponse: type: object properties: toolId: type: string description: Unique identifier of the tool that was executed. example: tool_X9pLm2Wq8Rt3 integrationId: type: string description: Unique identifier of the integration this tool belongs to. example: intg_AuUKK371Spr5 url: type: string description: "The fully resolved URL that was called, with all {{variable}}\ \ placeholders substituted." example: https://my-store.myshopify.com/admin/api/2024-01/customers/7654321.json method: type: string description: The HTTP method used for the request. example: GET statusCode: type: integer description: HTTP status code returned by the third-party API. format: int32 example: 200 success: type: boolean description: Whether the third-party API returned a 2xx success response. example: true responseBody: $ref: '#/components/schemas/JsonNode' responseHeaders: type: object additionalProperties: type: string description: Response headers returned by the third-party API. example: "{\"Content-Type\":\"application/json; charset=utf-8\"}" description: Response headers returned by the third-party API. example: Content-Type: application/json; charset=utf-8 errorMessage: type: string description: Error message when success is false — contains the raw error body or exception message. example: "404 Not Found: {\"errors\": \"Customer not found\"}" durationMs: type: integer description: "How long the third-party API took to respond, in milliseconds." format: int64 example: 342 executedAt: type: string description: Timestamp when the execution was triggered. format: date-time example: 2024-04-20T10:00:00Z mockToolDataId: type: string description: Public identifier of the mock created when saveAsMock was supplied on the execute request. example: mock_HaDxmGfwb8MZLlKM description: Result of executing a tool against its configured third-party API. PaginatedResponseIntegrationToolResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/IntegrationToolResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. SaveAsMockRequest: required: - agentId - name type: object properties: name: type: string description: Human-readable name for the captured mock. example: Success - Order Confirmed agentId: type: string description: The unique identifier of the agent this mock belongs to. example: agent_D5D0p7TUs66TTAEAx toolAlias: type: string description: "Optional agent step name used to resolve the tool when creating\ \ the mock. When omitted, the executed tool's toolId is used." example: get_order delay: type: integer description: Optional artificial delay in milliseconds to store on the mock. Defaults to 0. format: int64 example: 0 description: "When present on tool execute, persists the live request/response\ \ as a named mock in the tenant mock library and returns the created mockToolDataId." # Webhooks APIs Schemas CreateWebhookRequest: required: - agentId - events - name - url type: object properties: name: maxLength: 128 minLength: 1 type: string description: "Human-readable name for this webhook. Used to identify it\ \ in listings and dashboards. Does not need to be unique, but a descriptive\ \ name helps distinguish multiple webhooks on the same agent." example: Call Events - Production agentId: maxLength: 64 minLength: 1 type: string description: Unique identifier of the agent this webhook is scoped to. Only events originating from this agent will be delivered to this webhook's URL. Use the agentId returned when the agent was created. example: agent_D5D0p7TUs66TTAEAx url: pattern: https?://.+ type: string description: HTTPS endpoint that will receive event payloads as HTTP POST requests. Must be publicly reachable. The system expects an HTTP 2xx response within the configured timeout to confirm delivery. Non-2xx responses or timeouts are treated as delivery failures. example: https://yourapp.com/webhooks/sigmamind events: uniqueItems: true type: array description: Set of event types that will trigger a delivery to this webhook. 'conversation_started' fires when an agent session begins. 'conversation_ended' fires when a session closes. 'conversation_analysed' fires when post-call analysis is complete. At least one event must be specified. Only events in this set will be sent — all others are silently ignored. example: - conversation_started - conversation_ended items: type: string description: Set of event types that will trigger a delivery to this webhook. 'conversation_started' fires when an agent session begins. 'conversation_ended' fires when a session closes. 'conversation_analysed' fires when post-call analysis is complete. At least one event must be specified. Only events in this set will be sent — all others are silently ignored. example: "[\"conversation_started\",\"conversation_ended\"]" enum: - conversation_started - conversation_ended - conversation_analysed description: Request body to register a new webhook. A webhook delivers real-time event notifications to your server via HTTP POST whenever selected events occur on an agent. The receiving endpoint must be publicly reachable over HTTPS and return HTTP 2xx to acknowledge delivery. WebhookResponse: type: object properties: workspaceId: type: string description: Unique identifier of the workspace this webhook belongs to. Use this value to scope queries or filter webhooks by workspace. example: org_BUbkx3PsbzQm5V10 webhookId: type: string description: "Unique identifier for this webhook. Use this value as webhookId\ \ when updating, deleting, or retrieving this webhook via the API." example: wh_BUbkx3PsbzQm5V10 name: type: string description: Display name of this webhook as set at creation time. Used to identify it in listings and dashboards. example: Call Events - Production agentId: type: string description: Unique identifier of the agent this webhook is scoped to. Only events originating from this agent are delivered to this webhook's URL. example: agent_D5D0p7TUs66TTAEAx active: type: boolean description: "Whether this webhook is currently active and will receive\ \ event deliveries. When false, the webhook is registered but no events\ \ are sent to the URL. Toggle this to pause or resume delivery without\ \ deleting the webhook." example: true secret: type: string description: HMAC secret key used to sign outgoing webhook payloads. The system includes a signature header on each delivery computed using this secret. Verify the signature on your server to confirm payloads are genuinely from SigmaMind. Store this value securely — it is only returned at creation time. example: mK9vXq2pL8nR5tY1wA3sD6fH0jC4bE7u events: type: array description: Event types this webhook is subscribed to. Only events in this list trigger a delivery to the webhook URL. 'conversation_started' fires when an agent session begins. 'conversation_ended' fires when a session closes. 'conversation_analysed' fires when post-call analysis is complete. items: type: string description: Event types this webhook is subscribed to. Only events in this list trigger a delivery to the webhook URL. 'conversation_started' fires when an agent session begins. 'conversation_ended' fires when a session closes. 'conversation_analysed' fires when post-call analysis is complete. enum: - conversation_started - conversation_ended - conversation_analysed enum: - conversation_started - conversation_ended - conversation_analysed url: type: string description: "Full details of a registered webhook. Includes delivery target,\ \ the agent it is scoped to, active status, subscribed events, and the secret\ \ used to verify payload authenticity." PaginatedResponseWebhookResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/WebhookResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # API Keys APIs Schemas CreateApiKeyRequest: required: - name type: object properties: tenantOrgId: type: integer format: int64 name: maxLength: 100 minLength: 0 type: string description: "A descriptive name for the API key (max length: 100)." example: Default description: maxLength: 500 minLength: 0 type: string description: "An optional description for the API key (max length: 500)." example: Default API Key to access APIs ApiKeyResponse: type: object properties: id: type: integer description: The unique identifier of the API key. format: int64 keyId: type: string description: A system-generated key identifier. example: gsU1oqy8hZM name: type: string description: The name assigned to the API key. example: Default description: type: string description: The description of the API key. example: Default API Key to access APIs status: type: string description: The current status of the API key. example: active enum: - Active - Revoked - Expired expiresAt: type: string description: The expiration date and time of the API key. format: date-time example: 2021-04-20T10:00:00Z createdAt: type: string description: The date and time when the API key was created. format: date-time example: 2021-04-20T10:00:00Z secretKey: type: string description: The secret key value used to authenticate API requests. example: key_S7ULC2lBwbg.85ez_yKnXTG6I5OgDHwTBNMSOD2ZyyUFUuDgweVXcXE PaginatedResponseApiKeyResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/ApiKeyResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # Test Case APIs Schemas CreateTestCaseRequest: required: - agentId - successCriteria - userPrompt type: object properties: label: type: string description: "A human-readable name or label for the test case, used to\ \ identify it in reports and dashboards." example: Angry Customer - Cancellation Flow agentId: type: string description: The unique identifier of the Agent that will respond during the chat simulation. example: agent_D5D0p7TUs66TTAEAx llmModel: type: string description: "The LLM model used to generate Agent responses during the\ \ simulation. To use OpenAI priority tier models, append '-fast-tier'\ \ to the model name (e.g., 'gpt-4o-mini-fast-tier')." example: gpt-4o-mini enum: - gpt-5.2 - gpt-5.2-fast-tier - gpt-5.1 - gpt-5.1-fast-tier - gpt-5 - gpt-5-fast-tier - gpt-5-mini - gpt-5-mini-fast-tier - gpt-5-nano - gpt-4.1 - gpt-4.1-fast-tier - gpt-4.1-mini - gpt-4.1-mini-fast-tier - gpt-4.1-nano - gpt-4.1-nano-fast-tier - gpt-4o - gpt-4o-fast-tier - gpt-4o-mini - gpt-4o-mini-fast-tier - claude-haiku-4-5-20251001 - claude-sonnet-4-5-20250929 - claude-sonnet-4-20250514 - gemini-3.1-flash-lite-preview - gemini-3-flash-preview - gemini-2.5-flash-lite - gemini-2.5-flash mockData: type: array description: A list of mock variables that substitute for real external data sources during the simulation. Each entry defines a variable name and its simulated value. example: - variableName: customer_name value: John Doe - variableName: account_status value: active items: $ref: '#/components/schemas/MockDataRequest' mockToolData: type: array example: - mock_dpKjqjKnY3z6gABF items: type: string description: A list of identifiers of mock tool data to bind to this test case. Each entry is a mockToolDataId. example: "[\"mock_dpKjqjKnY3z6gABF\"]" userPrompt: type: string description: A prompt that defines the persona and intent of the simulated user. This drives the user-side messages throughout the conversation. example: You are an angry customer who wants to cancel their subscription. attempt: type: integer description: The number of times this test case should be executed. Each run is an independent simulation. Defaults to 1. format: int64 example: 5 successCriteria: type: string description: A plain-language description of what a successful agent response looks like. Used to evaluate the agent's performance after each simulation run. example: "The agent should acknowledge the cancellation request, present\ \ retention alternatives, and confirm the cancellation if the customer\ \ insists." UpdateTestCaseRequest: required: - agentId type: object properties: label: type: string description: "A human-readable name or label for the test case, used to\ \ identify it in reports and dashboards." example: Angry Customer - Cancellation Flow agentId: type: string description: The unique identifier of the Agent that will respond during the chat simulation. example: agent_D5D0p7TUs66TTAEAx llmModel: type: string description: "The LLM model used to generate Agent responses during the\ \ simulation. To use OpenAI priority tier models, append '-fast-tier'\ \ to the model name (e.g., 'gpt-4o-mini-fast-tier')." example: gpt-4o-mini enum: - gpt-5.2 - gpt-5.2-fast-tier - gpt-5.1 - gpt-5.1-fast-tier - gpt-5 - gpt-5-fast-tier - gpt-5-mini - gpt-5-mini-fast-tier - gpt-5-nano - gpt-4.1 - gpt-4.1-fast-tier - gpt-4.1-mini - gpt-4.1-mini-fast-tier - gpt-4.1-nano - gpt-4.1-nano-fast-tier - gpt-4o - gpt-4o-fast-tier - gpt-4o-mini - gpt-4o-mini-fast-tier - claude-haiku-4-5-20251001 - claude-sonnet-4-5-20250929 - claude-sonnet-4-20250514 - gemini-3.1-flash-lite-preview - gemini-3-flash-preview - gemini-2.5-flash-lite - gemini-2.5-flash mockData: type: array description: A list of mock variables that substitute for real external data sources during the simulation. Each entry defines a variable name and its simulated value. example: - variableName: customer_name value: John Doe - variableName: account_status value: active items: $ref: '#/components/schemas/MockDataRequest' mockToolData: type: array example: - mock_dpKjqjKnY3z6gABF items: type: string description: A list of identifiers of mock tool data to bind to this test case. Each entry is a mockToolDataId. example: "[\"mock_dpKjqjKnY3z6gABF\"]" userPrompt: type: string description: A prompt that defines the persona and intent of the simulated user. This drives the user-side messages throughout the conversation. example: You are an angry customer who wants to cancel their subscription. attempt: type: integer description: The number of times this test case should be executed. Each run is an independent simulation. Defaults to 1. format: int64 example: 5 successCriteria: type: string description: A plain-language description of what a successful agent response looks like. Used to evaluate the agent's performance after each simulation run. example: "The agent should acknowledge the cancellation request, present\ \ retention alternatives, and confirm the cancellation if the customer\ \ insists." MockDataRequest: type: object properties: variableName: type: string description: The name of the variable to be substituted with mock data during the simulation. Must match the variable name defined in the Agent's configuration. example: user_name value: type: string description: The simulated value assigned to the variable for the duration of the test run. example: John Doe description: A list of mock variables that substitute for real external data sources during the simulation. Each entry defines a variable name and its simulated value. example: - variableName: customer_name value: John Doe - variableName: account_status value: active TestCaseResponse: type: object properties: testCaseId: type: string description: The unique identifier of the test case. example: tc_d17T6uReChpyfFeP label: type: string description: "A human-readable name or label for the test case, used to\ \ identify it in reports and dashboards." example: Angry Customer - Cancellation Flow agent: $ref: '#/components/schemas/AgentResponse' workspaceId: type: string description: The unique identifier of the workspace under which this test case was created. example: org_V6eZ2zg8ziDx5pft llmModel: type: string description: The LLM model used to generate Agent responses during the simulation. example: gpt-4o-mini mockData: type: array description: The list of mock variables and their simulated values that were used to substitute for real external data sources during the simulation. example: - variableName: customer_name value: John Doe - variableName: account_status value: active items: $ref: '#/components/schemas/MockDataResponse' mockToolData: type: array description: Bindings from agent tool aliases to mock tool responses. May include resolved mock name and statusCode for the UI. example: - toolAlias: get_order mockToolDataId: mock_dpKjqjKnY3z6gABF name: Success - Empty List statusCode: 200 items: $ref: '#/components/schemas/MockToolDataJSON' userPrompt: type: string description: "The prompt that defined the persona and intent of the simulated\ \ user, driving the user-side messages throughout the conversation." example: You are an angry customer who wants to cancel your subscription. attempt: type: integer description: The number of times this test case was configured to run as independent simulation attempts. format: int64 example: 5 successCriteria: type: string description: "The plain-language description of what a successful agent\ \ response looks like, used to evaluate the agent's performance after\ \ each simulation run." example: "The agent should acknowledge the cancellation request, present\ \ retention alternatives, and confirm the cancellation if the customer\ \ insists." MockDataResponse: type: object properties: variableName: type: string description: The name of the variable that was substituted with mock data during the simulation. example: user_name value: type: string description: The simulated value that was assigned to the variable for the duration of the test run. example: John Doe description: The list of mock variables and their simulated values that were used to substitute for real external data sources during the simulation. example: - variableName: customer_name value: John Doe - variableName: account_status value: active PaginatedResponseTestCaseResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/TestCaseResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # Batch Run APIs Schemas BatchRunRequest: required: - agentId - testCases type: object properties: agentId: type: string description: The unique identifier of the Agent that will respond across all test cases in the batch simulation. example: agent_D5D0p7TUs66TTAEAx testCases: type: array description: A list of test case IDs to be executed together in a single batch run. Each test case will be simulated independently against the specified Agent. example: - tc_xeeXG5hX9dl0VFNt - tc_aQqGZoMIPbU5MXHV items: type: string description: A list of test case IDs to be executed together in a single batch run. Each test case will be simulated independently against the specified Agent. example: "[\"tc_xeeXG5hX9dl0VFNt\",\"tc_aQqGZoMIPbU5MXHV\"]" CreateBatchRunResponse: type: object properties: batchId: type: string description: The unique identifier of the newly created batch run. example: batch_s0OJu2JWR8R45Fai workspaceId: type: string description: The unique identifier of the workspace under which the batch run was created. example: org_V6eZ2zg8ziDx5pft agent: $ref: '#/components/schemas/AgentResponse' createdDate: type: string description: The UTC timestamp indicating when the batch run was created. format: date-time example: 2026-03-26T10:52:45.565905Z BatchResponse: type: object properties: batchId: type: string description: The unique identifier of the batch run. example: batch_s0OJu2JWR8R45Fai workspaceId: type: string description: The unique identifier of the workspace under which the batch run was created. example: org_V6eZ2zg8ziDx5pft agent: $ref: '#/components/schemas/AgentResponse' createdDate: type: string description: The UTC timestamp indicating when the batch run was created. format: date-time example: 2026-03-26T10:52:45.565905Z testCases: type: array description: "The list of test cases included in this batch run, along with\ \ their individual simulation results." items: $ref: '#/components/schemas/TestCaseResponse' successfulAttempts: type: integer description: The total number of simulation attempts across all test cases in this batch run that were evaluated as successful. format: int64 example: 4 failedAttempts: type: integer description: The total number of simulation attempts across all test cases in this batch run that were evaluated as failed. format: int64 example: 1 totalAttempts: type: integer description: The total number of simulation attempts executed across all test cases in this batch run. format: int64 example: 5 description: List of items for the current page. Contains up to 'size' number of records. PaginatedResponseBatchResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/BatchResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # Test Run APIs Schemas TestCaseRunResponse: type: object properties: batchId: type: string description: The unique identifier of the batch run this simulation attempt belongs to. example: batch_s0OJu2JWR8R45Fai workspaceId: type: string description: The unique identifier of the workspace under which this simulation attempt was created. example: org_V6eZ2zg8ziDx5pft agent: $ref: '#/components/schemas/AgentResponse' testCase: $ref: '#/components/schemas/TestCaseResponse' jobId: type: string description: The unique identifier of this individual simulation attempt within the batch run. example: job_ksUu5yRHGTLLrLeM chatId: type: string description: The unique identifier of the chat session generated during this simulation run. example: chat_IpELinkFvINQ1212 createdDate: type: string description: The UTC timestamp indicating when this simulation run was initiated. format: date-time example: 2026-03-26T10:52:45.565905Z completedDate: type: string description: The UTC timestamp indicating when this simulation run was completed. format: date-time example: 2026-03-26T10:54:45.565905Z isSuccessful: type: boolean description: Indicates whether the Agent met the success criteria during this simulation run. example: true remarks: type: string description: "A plain-language explanation of why the simulation run was\ \ evaluated as successful or failed, based on the success criteria." example: The Agent successfully maintained focus on the primary task of addressing the customer's order enquiry. conversation: type: array description: The full transcript of the conversation between the simulated user and the Agent during this simulation run. items: $ref: '#/components/schemas/ConversationResponse' description: List of items for the current page. Contains up to 'size' number of records. ConversationResponse: type: object properties: role: type: string description: The role of the participant who sent this message in the simulation. Indicates whether the message was generated by the simulated user or the Agent. example: user content: type: string description: The message content produced by the participant for this turn in the conversation. example: I want to cancel my subscription immediately. description: The full transcript of the conversation between the simulated user and the Agent during this simulation run. PaginatedResponseTestCaseRunResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/TestCaseRunResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # QA Rule APIs Schemas CreateQARuleRequest: required: - agentIds - evaluationCriteria - ruleName type: object properties: ruleName: type: string description: "The name of the QA rule, used to identify it in rule lists\ \ and evaluation reports." example: Tone & Professionalism Check ruleDescription: type: string description: A brief explanation of what this QA rule evaluates and its intended purpose. example: Ensures agents maintain a professional and empathetic tone throughout the conversation. evaluationCriteria: type: string description: The specific criteria used to evaluate agent responses against this rule. example: "Evaluate whether agent greeted the customer by name, avoided interrupting,\ \ and closed with a resolution summary." expectedValue: type: boolean description: "The expected outcome of the evaluation criteria that determines\ \ a successful QA result. Set to true if the evaluation criteria returning\ \ true should be treated as a Success, or false if the evaluation criteria\ \ returning true should be treated as a Fail. Default is true." example: true enum: - true - false agentIds: type: array description: List of agent Ids on which QA rule would apply example: - agent_D5D0p7TUs66TTAEAx items: type: string # description: List of agent Ids on which QA rule would apply example: "[\"agent_D5D0p7TUs66TTAEAx\"]" UpdateQARuleRequest: type: object properties: ruleName: type: string description: "The name of the QA rule, used to identify it in rule lists\ \ and evaluation reports." example: Tone & Professionalism Check ruleDescription: type: string description: A brief explanation of what this QA rule evaluates and its intended purpose. example: Ensures agents maintain a professional and empathetic tone throughout the conversation. evaluationCriteria: type: string description: The specific criteria used to evaluate agent responses against this rule. example: "Evaluate whether agent greeted the customer by name, avoided interrupting,\ \ and closed with a resolution summary." expectedValue: type: boolean description: "The expected outcome of the evaluation criteria that determines\ \ a successful QA result. Set to true if the evaluation criteria returning\ \ true should be treated as a Success, or false if the evaluation criteria\ \ returning true should be treated as a Fail." example: true enum: - true - false agentIds: type: array description: List of agent Ids on which QA rule would apply example: - agent_D5D0p7TUs66TTAEAx items: type: string # description: List of agent Ids on which QA rule would apply example: "[\"agent_D5D0p7TUs66TTAEAx\"]" QARuleResponse: type: object properties: qaRuleId: type: string description: The unique identifier of the QA rule. example: rule_YYdKgw1masomMfe8 workspaceId: type: string description: The unique identifier of the workspace this QA rule belongs to. example: org_V6eZ2zg8ziDx5pft ruleName: type: string description: "The name of the QA rule, used to identify it in rule lists\ \ and evaluation reports." example: Tone & Professionalism Check ruleDescription: type: string description: A brief explanation of what this QA rule evaluates and its intended purpose. example: Ensures agents maintain a professional and empathetic tone throughout the conversation. agents: type: array items: $ref: '#/components/schemas/AgentResponse' evaluationCriteria: type: string description: The specific criteria or rubric used to evaluate agent responses against this rule. example: "Evaluate whether agent greeted the customer by name, avoided interrupting,\ \ and closed with a resolution summary." expectedValue: type: boolean description: "The expected evaluation result that determines whether the\ \ QA rule is satisfied. When the evaluation criteria returns a result\ \ matching this expected value, the interaction is marked as a Success;\ \ otherwise it is marked as a Fail." example: true PaginatedResponseQARuleResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/QARuleResponse' page: type: integer format: int32 size: type: integer format: int32 totalCount: type: integer format: int64 totalPages: type: integer format: int32 hasNext: type: boolean hasPrevious: type: boolean # QA Issue APIs Schemas QAIssueResponse: type: object properties: qaIssueId: type: string description: The unique identifier of the QA issue. example: issue_1fueLBh6mJxwLbe1 qaRuleId: type: string description: The unique identifier of the QA rule that triggered this issue. example: rule_YYdKgw1masomMfe8 workspaceId: type: string description: The unique identifier of the workspace in which this QA issue was raised. example: org_GdDTrzEppfUfSZPE agentId: type: string description: The unique identifier of the agent whose interaction triggered this QA issue. example: agent_D5D0p7TUs66TTAEAx callId: type: string description: The unique identifier of the call or chat associated with this QA issue. example: call-H0eS7imseNUp0jCM channel: type: string description: The communication channel through which the interaction occurred that raised this QA issue. example: voice enum: - chat - voice result: type: string description: The outcome of the QA evaluation for this issue. Reflects whether the agent's interaction met or failed the associated QA rule's evaluation criteria. example: Fail enum: - Success - Fail remarks: type: string description: Additional remarks or context provided by the evaluator regarding this QA issue. example: Agent failed to acknowledge the customer's frustration before proceeding with troubleshooting. qaRuleSnapshot: $ref: '#/components/schemas/QARuleResponse' PaginatedResponseQAIssueResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/QAIssueResponse' page: type: integer format: int32 size: type: integer format: int32 totalCount: type: integer format: int64 totalPages: type: integer format: int32 hasNext: type: boolean hasPrevious: type: boolean # Knowledge Base KnowledgeBaseFileResponse: required: - content - documentId - type type: object properties: documentId: maxLength: 128 minLength: 1 pattern: "^[a-zA-Z0-9_-]{1,128}$" type: string description: Stable id for this source; use when updating or deleting a single document. example: doc_a1b2c3d4e5f67890 type: type: string description: Source row kind. In JSON request and response bodies. example: url enum: - file - url - text content: type: string description: "Stored link, path, or text for this source." example: https://docs.example.com/guide description: One source inside a knowledge base. KnowledgeBaseResponse: required: - createdAt - files - kbId - name - updatedAt type: object properties: kbId: maxLength: 64 minLength: 1 type: string description: "Use this id in the URL when fetching, updating, or deleting\ \ this knowledge base." example: kb_6sbr3tbMX757M0VD name: maxLength: 512 type: string description: Knowledge base name example: Support FAQs files: type: array description: "Ordered sources; each item has documentId, type, and content." items: $ref: '#/components/schemas/KnowledgeBaseFileResponse' createdAt: type: string description: When the knowledge base was created. format: date-time example: 2026-05-06T16:45:02.073127+05:30 updatedAt: type: string description: When the knowledge base or its sources were last changed. format: date-time example: 2026-05-06T16:45:02.073127+05:30 description: A knowledge base and its sources. PaginatedResponseKnowledgeBaseResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/KnowledgeBaseResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. # Other Schemas AgentResponse: type: object properties: name: type: string description: The display name of the assigned agent. example: New AI Agent agentId: type: string description: The unique identifier of the agent within the system. example: agent_D5D0p7TUs66TTAEAx status: type: string description: The current operational status of the agent. example: Live enum: - Live - Testing - Disabled description: "Agent assigned to handle all calls in this campaign. Contains\ \ the agent's ID, name, and current status. All contacts in the campaign's\ \ contact list will be called using this agent." JsonNode: type: object description: "Dynamic key-value pairs that were passed to the agent at call\ \ start for personalisation. Keys correspond to variable names defined in\ \ the agent's configuration (e.g., 'customer_name', 'account_id'). Null or\ \ empty if no dynamic variables were provided when the call was created." example: customer_name: Michael account_id: ACC-001 # Error Schema Error: type: object properties: timestamp: type: string description: Error timestamp in ISO format format: date-time status: type: integer description: HTTP status code example: 400 error: type: string description: Error type or HTTP status message example: Bad Request message: type: string description: Detailed error message example: Email is required path: type: string description: Request path where error occurred example: /v1/users validationErrors: type: object description: Field validation errors (if any) example: |- { "email": "Email is required", "name": "Name is too short" } description: Standard error response # Mock Tool Data MockToolDataRequest: required: - mockToolDataId - toolAlias type: object properties: toolAlias: type: string description: Tool alias on the agent that this mock should satisfy during simulation. example: get_order mockToolDataId: type: string description: Public identifier of the mock tool data library record. example: mock_dpKjqjKnY3z6gABF name: type: string description: Display name of the linked mock (resolved on read for the UI). example: Success - Empty List statusCode: type: integer description: HTTP status code of the linked mock (resolved on read for the UI). format: int32 example: 200 description: Bindings from agent tool aliases to mock tool responses in the mock library. Replaces the full list when provided. Use toolAlias (not toolId). example: - toolAlias: get_order mockToolDataId: mock_dpKjqjKnY3z6gABF MockToolDataJSON: required: - mockToolDataId - toolAlias type: object properties: toolAlias: type: string description: Tool alias on the agent that this mock should satisfy during simulation. example: get_order mockToolDataId: type: string description: Public identifier of the mock tool data library record. example: mock_dpKjqjKnY3z6gABF name: type: string description: Display name of the linked mock (resolved on read for the UI). example: Success - Empty List statusCode: type: integer description: HTTP status code of the linked mock (resolved on read for the UI). format: int32 example: 200 description: Bindings from agent tool aliases to mock tool responses. May include resolved mock name and statusCode for the UI. example: - toolAlias: get_order mockToolDataId: mock_dpKjqjKnY3z6gABF name: Success - Empty List statusCode: 200 MockToolDataResponse: type: object properties: mockToolDataId: type: string description: Public identifier of the mock tool data record. example: mock_dpKjqjKnY3z6gABF name: type: string description: Human-readable name for this mock. example: Success - Order Confirmed agentId: type: string description: The unique identifier of the agent this mock belongs to. example: agent_D5D0p7TUs66TTAEAx toolId: type: string description: Public identifier of the integration tool this mock belongs to. example: tool_X9pLm2Wq8Rt3 toolAlias: type: string description: Agent tool alias this mock was created against. example: get_order toolName: type: string description: Display name of the tool at the time the mock was created. example: Get Order request: type: object description: Request payload (or placeholders) associated with this mock. example: order_id: "1073460023" response: type: object description: Mocked HTTP response body. example: order: id: 1073460023 confirmation_number: A50GQT45C confirmed: true created_at: 2026-07-01T12:34:26-04:00 currency: EUR current_subtotal_price: "224.97" current_subtotal_price_set: shop_money: amount: "224.97" currency_code: EUR presentment_money: amount: "224.97" currency_code: EUR statusCode: type: integer description: HTTP status code returned when this mock is used. format: int32 example: 200 delay: type: integer description: Artificial delay in milliseconds before returning the mock response. format: int64 example: 500 description: A mock tool response stored in the tenant mock library. PaginatedResponseMockToolDataResponse: type: object properties: data: type: array description: List of items for the current page. Contains up to 'size' number of records. items: $ref: '#/components/schemas/MockToolDataResponse' page: type: integer description: Current page number (0-based index). Indicates which page of results is being returned. format: int32 example: 0 size: type: integer description: Number of items requested per page. Determines the maximum size of the 'data' list. format: int32 example: 20 totalCount: type: integer description: Total number of records available across all pages. Useful for calculating pagination on the client side. format: int64 example: 125 totalPages: type: integer description: Total number of pages available based on totalCounts and size. Helps clients understand how many pages exist in total. format: int32 example: 7 hasNext: type: boolean description: Indicates whether there is a next page available after the current one. Useful for implementing 'Load More' or next navigation. example: true hasPrevious: type: boolean description: Indicates whether there is a previous page before the current one. Useful for enabling backward navigation. example: false description: Standard wrapper for paginated API responses. Use this when returning list data that is split across multiple pages. Includes the current page of results along with pagination metadata to help clients navigate through large datasets efficiently. UpdateMockToolDataRequest: required: - agentId type: object properties: name: maxLength: 255 minLength: 0 pattern: .*\S.* type: string description: Human-readable name for this mock. example: Success - Order Confirmed agentId: type: string description: The unique identifier of the agent this mock belongs to. example: agent_D5D0p7TUs66TTAEAx request: type: object description: Optional request payload associated with this mock. example: order_id: "1073460023" response: type: object description: Mocked HTTP response body. example: order: id: 1073460023 confirmation_number: A50GQT45C confirmed: true created_at: 2026-07-01T12:34:26-04:00 currency: EUR current_subtotal_price: "224.97" current_subtotal_price_set: shop_money: amount: "224.97" currency_code: EUR presentment_money: amount: "224.97" currency_code: EUR statusCode: maximum: 599 minimum: 100 type: integer description: HTTP status code to return when this mock is used. format: int32 example: 200 enum: - 100 - 101 - 102 - 103 - 200 - 201 - 202 - 203 - 204 - 205 - 206 - 207 - 208 - 226 - 300 - 301 - 302 - 303 - 304 - 307 - 308 - 400 - 401 - 402 - 403 - 404 - 405 - 406 - 407 - 408 - 409 - 410 - 411 - 412 - 413 - 414 - 415 - 416 - 417 - 418 - 421 - 422 - 423 - 424 - 425 - 426 - 428 - 429 - 431 - 451 - 500 - 501 - 502 - 503 - 504 - 505 - 506 - 507 - 508 - 510 - 511 delay: maximum: 30000 minimum: 0 type: integer description: Artificial delay in milliseconds before returning the mock response. format: int64 example: 0 toolAlias: type: string description: Agent tool alias this mock belongs to. example: get_order description: Partial update for a mock tool data library record. Only provided fields are updated. CreateMockToolDataRequest: required: - agentId - name - response - statusCode - toolAlias type: object properties: name: maxLength: 255 minLength: 0 type: string description: "Human-readable name for this mock, used when picking mocks\ \ in the test-case UI." example: Success - Order Confirmed agentId: type: string description: The unique identifier of the agent this mock belongs to. example: agent_D5D0p7TUs66TTAEAx toolId: type: string description: Identifier of the integration tool this mock belongs to. Optional when toolAlias can uniquely resolve the tool. example: tool_X9pLm2Wq8Rt3 request: type: object description: "Optional request payload (or placeholders) associated with\ \ this mock, for documentation and capture." example: order_id: "1073460023" response: type: object description: Mocked HTTP response body returned when this mock is used during simulation. example: order: id: 1073460023 confirmation_number: A50GQT45C confirmed: true created_at: 2026-07-01T12:34:26-04:00 currency: EUR current_subtotal_price: "224.97" current_subtotal_price_set: shop_money: amount: "224.97" currency_code: EUR presentment_money: amount: "224.97" currency_code: EUR statusCode: maximum: 599 minimum: 100 type: integer description: HTTP status code to return when this mock is used. format: int32 example: 200 enum: - 100 - 101 - 102 - 103 - 200 - 201 - 202 - 203 - 204 - 205 - 206 - 207 - 208 - 226 - 300 - 301 - 302 - 303 - 304 - 307 - 308 - 400 - 401 - 402 - 403 - 404 - 405 - 406 - 407 - 408 - 409 - 410 - 411 - 412 - 413 - 414 - 415 - 416 - 417 - 418 - 421 - 422 - 423 - 424 - 425 - 426 - 428 - 429 - 431 - 451 - 500 - 501 - 502 - 503 - 504 - 505 - 506 - 507 - 508 - 510 - 511 delay: maximum: 30000 minimum: 0 type: integer description: Artificial delay in milliseconds before returning the mock response. Defaults to 0. format: int64 example: 500 toolAlias: type: string description: Agent tool alias this mock is bound to. example: get_order description: Request body to create a named mock tool response in the tenant mock library. securitySchemes: apiKeyAuth: type: apiKey description: Authenticate every request by passing your API key in the `X-API-Key` header. To get your key, go to Dashboard → API Keys and create or copy your Production API key. name: X-API-Key in: header