{ "openapi": "3.0.3", "info": { "title": "Callin Public API", "version": "1.0.0", "description": "The Callin public API lets you programmatically build and manage AI voice agents, control their knowledge bases, and retrieve call logs and transcripts. All endpoints are versioned under /public/v1." }, "servers": [ { "url": "https://api.callin.io/api", "description": "API Endpoint" } ], "tags": [ { "name": "Health", "description": "Service availability check. No authentication required." }, { "name": "Identity", "description": "Verify which account is associated with the current API key." }, { "name": "Agents", "description": "Create, retrieve, and update AI voice agents." }, { "name": "Conversations", "description": "List and inspect call logs, transcripts, and conversation details." }, { "name": "Knowledge Base", "description": "Manage documents and groups that agents use during calls." }, { "name": "Campaigns", "description": "..." }, { "name": "Contacts", "description": "..." } ], "paths": { "/public/health": { "get": { "tags": [ "Health" ], "summary": "Health check", "responses": { "200": { "description": "Service is up and healthy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessHealthResponse" } } } } }, "description": "Returns 200 OK when the service is running. No authentication required. Use this to verify connectivity or monitor uptime." } }, "/public/v1/me": { "get": { "tags": [ "Identity" ], "summary": "Get current identity", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Identity payload for the authenticated API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessMeResponse" } } } }, "401": { "description": "No API key was provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The API key is invalid or has been revoked (e.g. after regeneration).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns the userId and email associated with the API key in the request. Useful for confirming which account a key belongs to." } }, "/public/v1/agents": { "get": { "tags": [ "Agents" ], "summary": "List agents", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter agents by name (case-insensitive partial match)." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "name", "created_at" ] }, "description": "Field to sort by. Defaults to created_at." }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Sort order. Defaults to desc." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor from the previous response nextCursor. Pass an ISO timestamp when sorting by created_at, or a name string when sorting by name." }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "description": "Number of agents per page. Min 1, max 100, default 30." } ], "responses": { "200": { "description": "A paginated array of agents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessAgentListResponse" } } } }, "400": { "description": "One or more query parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a paginated list of AI voice agents in your account. Use search to filter by name, sortBy and sortDirection to control ordering, and cursor and pageSize to page through results." } }, "/public/v1/agents/{agentId}": { "get": { "tags": [ "Agents" ], "summary": "Get agent", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the agent." } ], "responses": { "200": { "description": "Full agent details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessAgentDetailsResponse" } } } }, "404": { "description": "No agent found with the given agentId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns the full configuration and metadata for a single agent by its ID." }, "patch": { "tags": [ "Agents" ], "summary": "Update agent", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the agent to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" }, "example": {} } } }, "responses": { "200": { "description": "Agent updated successfully. Returns the full updated agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessAgentDetailsResponse" } } } }, "404": { "description": "No agent found with the given agentId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request body failed validation. Check the error field for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Partially updates an agent. Only fields included in the request body are changed; omitted fields remain unchanged. Returns the full updated agent on success." } }, "/public/v1/agents/create": { "post": { "tags": [ "Agents" ], "summary": "Create agent", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" }, "example": { "name": "My Agent", "conversationConfig": { "agent": { "prompt": { "prompt": "You are a helpful assistant." } } } } } } }, "responses": { "200": { "description": "Agent created successfully. Returns the new agent data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessCreateAgentResponse" } } } }, "422": { "description": "Request body failed validation. Check the error field for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a new AI voice agent. The name, voice_id, primary_language, prompt, and llm fields are required. All other fields are optional and fall back to sensible defaults." } }, "/public/v1/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List conversations", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "agentId", "in": "query", "schema": { "type": "string" }, "description": "Filter conversations to a specific agent." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "completed", "in_progress", "cancelled", "failed", "scheduled" ], "example": "completed" }, "description": "Filter by conversation status: completed, in_progress, cancelled, failed, or scheduled." }, { "name": "startBeforeUnix", "in": "query", "schema": { "type": "number" }, "description": "Return conversations that started before this Unix timestamp (seconds or milliseconds)." }, { "name": "startAfterUnix", "in": "query", "schema": { "type": "number" }, "description": "Return conversations that started after this Unix timestamp (seconds or milliseconds)." }, { "name": "minCallDuration", "in": "query", "schema": { "type": "number", "minimum": 0 }, "description": "Return only conversations with a duration of at least this many seconds." }, { "name": "maxCallDuration", "in": "query", "schema": { "type": "number", "minimum": 0 }, "description": "Duration in seconds" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "ISO timestamp" }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "A paginated array of conversation summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessConversationListResponse" } } } }, "400": { "description": "Invalid query params", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a paginated list of call conversations. Filter by agent, status, date range, or minimum call duration. Use cursor and pageSize to page through large result sets." } }, "/public/v1/conversations/{conversationId}": { "get": { "tags": [ "Conversations" ], "summary": "Get conversation", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the conversation." } ], "responses": { "200": { "description": "Full conversation details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessConversationDetailsResponse" } } } }, "404": { "description": "No conversation found with the given conversationId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns full details for a single conversation including the transcript, sentiment analysis, key moments, collected data, and call metadata." } }, "/public/v1/conversations/{conversationId}/audio": { "get": { "tags": [ "Conversations" ], "summary": "Get call recording", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the conversation." } ], "responses": { "200": { "description": "Audio file stream for the call recording.", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/x-wav": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No recording found for the given conversationId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Audio fetch failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Failed to fetch recording" } } } } } } }, "description": "Returns the audio recording for a conversation. Only available when call recording is enabled on the agent." } }, "/public/v1/knowledge-base/documents": { "get": { "tags": [ "Knowledge Base" ], "summary": "List documents", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Used for fetching next page. Cursor is returned in the response." }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "description": "How many documents to return at maximum. Can not exceed 100, defaults to 30." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search for documents by name" }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "name", "created_at" ] }, "description": "The field to sort the results by" }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "The direction to sort the results" } ], "responses": { "200": { "description": "Documents list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessDocumentListResponse" } } } }, "400": { "description": "Invalid query params", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a paginated list of knowledge base documents available to your agents." } }, "/public/v1/knowledge-base/documents/{documentId}": { "get": { "tags": [ "Knowledge Base" ], "summary": "Get document", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the document" } ], "responses": { "200": { "description": "Document details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessDocumentDetailsResponse" } } } }, "400": { "description": "Invalid document ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns the content and metadata for a single knowledge base document." } }, "/public/v1/knowledge-base/groups": { "get": { "tags": [ "Knowledge Base" ], "summary": "List groups", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Used for fetching next page. Cursor is returned in the response." }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "description": "How many groups to return at maximum. Can not exceed 100, defaults to 30." }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search for groups by name" }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "name", "created_at" ] }, "description": "The field to sort the results by" }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "The direction to sort the results" } ], "responses": { "200": { "description": "Groups list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessGroupListResponse" } } } }, "400": { "description": "Invalid query params", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Returns a paginated list of knowledge base groups used to organise documents." } }, "/public/v1/knowledge-base/groups/{groupId}": { "patch": { "tags": [ "Knowledge Base" ], "summary": "Update group", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the group" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGroupRequest" } } } }, "responses": { "200": { "description": "Group updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessGroupUpdateDetailsResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Partially updates a knowledge base group." } }, "/public/v1/knowledge-base/documents/url": { "post": { "tags": [ "Knowledge Base" ], "summary": "Create document from URL", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentFromUrlRequest" } } } }, "responses": { "200": { "description": "Document created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessDocumentUrlCreateResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Fetches content from the provided URL and creates a new knowledge base document from it." } }, "/public/v1/knowledge-base/documents/file": { "post": { "tags": [ "Knowledge Base" ], "summary": "Upload document file", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateDocumentFromFileRequest" } } } }, "responses": { "200": { "description": "Document created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessDocumentCreateFromFileResponse" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Uploads a file (PDF, DOCX, TXT, etc.) and creates a new knowledge base document from its contents." } }, "/public/v1/campaigns": { "get": { "tags": ["Campaigns"], "summary": "List campaigns", "description": "Returns campaigns for the API key account. Contacts are omitted; use the campaign detail route for the contact list.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive match on the campaign name." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["draft", "waiting", "running", "paused", "stopped", "completed", "failed", "delayed"] } }, { "name": "agentId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "createdAt of the last campaign from the previous page." }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "includeDeleted", "in": "query", "schema": { "type": "string", "enum": ["true", "false"] } } ], "responses": { "200": { "description": "Campaign list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessCampaignListResponse" } } } } } }, "post": { "tags": ["Campaigns"], "summary": "Create a campaign", "description": "Saves a campaign for an agent that already has a phone number. Every phone number must be E.164, like +14155552671. Set launch to dial immediately, or scheduled with a future window. Omit both to save a draft. Extra contact fields are passed to the agent as dynamic variables. Follow-up calls run when a call ends as busy or no-answer.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignRequest" } } } }, "responses": { "201": { "description": "Campaign created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessCampaignResponse" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/public/v1/campaigns/csv": { "post": { "tags": ["Campaigns"], "summary": "Create a campaign from a CSV", "description": "Creates or starts a campaign only when every CSV row is valid. A file with an invalid phone, invalid email, or a duplicate number is rejected and nothing is saved or dialed. Phone numbers must be E.164, like +14155552671. Spaces and punctuation are removed, and a leading 00 is converted to +. Send multipart field file plus name and agentId. Set launch to true to dial immediately, or scheduled with startTime, endTime, and timezone. Optional phoneColumn, nameColumn, and emailColumn override the headers.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateCampaignCsvUpload" } } } }, "responses": { "201": { "description": "Campaign created from a valid CSV", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessCampaignResponse" } } } }, "400": { "description": "CSV is not valid. The campaign was not created. error.details contains the row report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/public/v1/campaigns/{campaignId}": { "get": { "tags": ["Campaigns"], "summary": "Get a campaign", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Campaign details, including contacts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessCampaignResponse" } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": ["Campaigns"], "summary": "Update a campaign", "description": "Rejected while the campaign is running. Changing contacts, the agent, or the schedule replaces a waiting job.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCampaignRequest" } } } }, "responses": { "200": { "description": "Campaign updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessCampaignResponse" } } } } } }, "delete": { "tags": ["Campaigns"], "summary": "Delete a campaign", "description": "Soft-deletes the campaign and removes a waiting job. A running campaign must be stopped first.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Campaign deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessCampaignResponse" } } } }, "409": { "description": "Campaign is running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/public/v1/campaigns/{campaignId}/launch": { "post": { "tags": ["Campaigns"], "summary": "Launch a campaign now", "description": "Dials contacts from startIndex, or from the saved resume index when a scheduled job is replaced. Requires an active subscription with minutes remaining.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchCampaignRequest" } } } }, "responses": { "200": { "description": "Campaign launched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessCampaignResponse" } } } } } } }, "/public/v1/campaigns/{campaignId}/schedule": { "post": { "tags": ["Campaigns"], "summary": "Schedule a campaign", "description": "Queues dialing at startTime in the given IANA timezone, and pauses until the next day's startTime after endTime. A paused or stopped campaign resumes from its saved contact index.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleCampaignRequest" } } } }, "responses": { "200": { "description": "Campaign scheduled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessCampaignResponse" } } } } } } }, "/public/v1/campaigns/{campaignId}/stop": { "post": { "tags": ["Campaigns"], "summary": "Stop a campaign", "description": "Removes a waiting or paused job immediately. A running job stops before the next contact.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Campaign stopped, or stopping if a call loop is in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessCampaignResponse" } } } } } } }, "/public/v1/campaigns/{campaignId}/calls": { "get": { "tags": ["Campaigns"], "summary": "List calls for a campaign", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "campaignId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Campaign calls", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessCampaignCallListResponse" } } } } } } }, "/public/v1/contacts": { "get": { "tags": ["Contacts"], "summary": "List contacts", "description": "Returns contacts saved on the API key account. Use contactId values with POST /public/v1/campaigns.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Matches phone number, name, or email." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "createdAt of the last contact from the previous page." }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Contact list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessContactListResponse" } } } } } }, "post": { "tags": ["Contacts"], "summary": "Create a contact", "description": "Stores one contact. Phone numbers are saved without spaces or punctuation. A duplicate phone number returns 409. Extra fields are kept and can be used as campaign dynamic variables.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactWrite" } } } }, "responses": { "201": { "description": "Contact created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessContactResponse" } } } }, "409": { "description": "Phone number already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/public/v1/contacts/csv/verify": { "post": { "tags": ["Contacts"], "summary": "Verify a contact CSV", "description": "Parses one UTF-8 .csv file and checks every row without saving. Phone numbers must be E.164, like +14155552671. Send multipart form field file. Optional phoneColumn, nameColumn, and emailColumn override the header mapping when the file does not use phoneNumber, name, or email. A phone column is required. Each row is valid, invalid, duplicate, or already on the account. The maximum is 2000 data rows and 10MB.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ContactCsvUpload" } } } }, "responses": { "200": { "description": "Row-by-row verification. Nothing is saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessContactCsvVerifyResponse" } } } } } } }, "/public/v1/contacts/csv": { "post": { "tags": ["Contacts"], "summary": "Upload a contact CSV", "description": "Verifies the CSV, then creates the valid rows that are not already on the account. Invalid and duplicate rows are reported and not saved. The same file field and column overrides as verification are accepted.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ContactCsvUpload" } } } }, "responses": { "200": { "description": "Verification plus the contacts that were created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessContactCsvImportResponse" } } } } } } }, "/public/v1/contacts/import": { "post": { "tags": ["Contacts"], "summary": "Import contacts", "description": "Creates up to 2000 contacts. Numbers already on the account are skipped. Duplicate numbers in the same request keep the last row. The created contactId values can be passed to a campaign as contactIds.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportContactsRequest" } } } }, "responses": { "200": { "description": "Import result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessContactImportResponse" } } } } } } }, "/public/v1/contacts/delete": { "post": { "tags": ["Contacts"], "summary": "Delete contacts", "description": "Deletes the given contacts owned by the API key account. Unknown ids are ignored.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteContactsRequest" } } } }, "responses": { "200": { "description": "Delete result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessContactDeleteResponse" } } } } } } }, "/public/v1/contacts/{contactId}": { "get": { "tags": ["Contacts"], "summary": "Get a contact", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessContactResponse" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": ["Contacts"], "summary": "Update a contact", "description": "Merges the sent fields into the contact. Omitted fields are left as they are.", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactWrite" } } } }, "responses": { "200": { "description": "Contact updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessContactResponse" } } } } } }, "delete": { "tags": ["Contacts"], "summary": "Delete a contact", "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "ApiKeyQuery": [] } ], "parameters": [ { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Contact deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessContactDeleteOneResponse" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Send your Callin API key in the `x-api-key` header." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Same API key as a Bearer token: `Authorization: Bearer `." } }, "schemas": { "ErrorResponse": { "type": "object", "description": "Returned for most client and validation errors. Read `error.message` and optional `error.fields` for details.", "properties": { "success": { "type": "boolean", "example": false, "description": "Always `false` for this shape." }, "error": { "type": "object", "description": "Structured error payload from the API.", "properties": { "code": { "type": "string", "description": "Stable machine-oriented error code when provided." }, "message": { "type": "string", "description": "Human-readable explanation suitable to show or log." }, "status": { "type": "integer", "description": "HTTP status code echoed for convenience." }, "fields": { "type": "array", "description": "Optional per-field validation issues (shape is endpoint-specific).", "items": { "type": "object" } } } } } }, "MetaCreatedBy": { "type": "object", "properties": { "userId": { "type": "string", "description": "The ID of the user who created the item" }, "userEmail": { "type": "string", "description": "The email of the user who created the item" } } }, "SuccessHealthResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "scope": { "type": "string", "example": "public" } } } }, "description": "Public health check payload (`success` + small `data` object)." }, "SuccessMeResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Indicates if the request was successful" }, "data": { "type": "object", "properties": { "userId": { "type": "string", "description": "The ID of the user" }, "email": { "type": "string", "description": "The email of the user" } } } }, "description": "Who the current API key belongs to (`userId`, `email`)." }, "AgentListItem": { "type": "object", "properties": { "agentId": { "type": "string", "description": "The ID of the agent" }, "name": { "type": "string", "description": "The name of the agent" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Agent tags used to categorize the agent" }, "metadata": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the agent was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time the agent was last updated" }, "createdBy": { "$ref": "#/components/schemas/MetaCreatedBy" } } } } }, "SuccessAgentListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "A list of agents and their metadata", "type": "array", "items": { "$ref": "#/components/schemas/AgentListItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "description": "Paginated list of agents with cursor metadata." }, "AgentDetails": { "type": "object", "properties": { "agentId": { "type": "string", "description": "The ID of the agent" }, "name": { "type": "string", "description": "The name of the agent" }, "direction": { "type": "string", "description": "The direction of the agent", "enum": [ "outbound", "inbound", "both" ], "example": "outbound" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "The tags of the agent" }, "conversationConfig": { "type": "object", "$ref": "#/components/schemas/AgentConversationConfiguration", "description": "The conversation configuration of the agent" }, "platformSettings": { "type": "object", "$ref": "#/components/schemas/AgentPlatformSettings", "description": "The platform settings of the agent" }, "phoneNumbers": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "number": { "type": "string" }, "label": { "type": "string" } } }, "description": "The phone numbers of the agent" }, "workflow": { "type": "object", "properties": { "edges": { "type": "object" }, "nodes": { "type": "object" }, "preventSubagentLoops": { "type": "boolean", "default": false } }, "description": "The workflow of the agent" }, "metadata": { "type": "object", "properties": { "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "createdBy": { "$ref": "#/components/schemas/MetaCreatedBy" } }, "description": "The metadata of the agent" } } }, "SuccessAgentDetailsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AgentDetails" } }, "description": "Full single-agent record including conversation and platform configuration." }, "CreateAgentRequest": { "type": "object", "required": [ "name", "conversationConfig" ], "description": "Create-agent payload (createPublicAgentSchema): name, direction, tags, nested conversationConfig and platformSettings.", "properties": { "name": { "type": "string", "description": "Display name for the agent." }, "direction": { "type": "string", "enum": [ "outbound", "inbound", "both" ], "description": "Whether the agent handles outbound calls, inbound calls, or both. Defaults to outbound." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing agents." }, "conversationConfig": { "$ref": "#/components/schemas/AgentConversationConfiguration" }, "platformSettings": { "$ref": "#/components/schemas/AgentPlatformSettings" } }, "example": { "name": "My Agent", "prompt": "You are a helpful assistant." } }, "UpdateAgentRequest": { "type": "object", "description": "Partial update payload for an agent. All fields are optional \u2014 include only the fields you want to change. Omitted fields remain unchanged.", "properties": { "name": { "type": "string", "description": "Display name for the agent." }, "direction": { "type": "string", "enum": [ "outbound", "inbound", "both" ], "description": "Supported call direction." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for organizing agents." }, "conversationConfig": { "$ref": "#/components/schemas/UpdateAgentConversationConfiguration" }, "platformSettings": { "$ref": "#/components/schemas/PatchAgentPlatformSettings" } }, "example": {} }, "SuccessCreateAgentResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "agentId": { "type": "string", "description": "The ID of the agent created" } } } }, "description": "After creating an agent, use `data.agentId` in follow-up calls." }, "ConversationListItem": { "type": "object", "properties": { "conversationId": { "type": "string", "description": "The ID of the conversation" }, "agentId": { "type": "string", "description": "The ID of the agent" }, "startTimeUnix": { "type": "integer", "nullable": true, "description": "The start time of the conversation in Unix timestamp" }, "endTimeUnix": { "type": "integer", "nullable": true, "description": "The end time of the conversation in Unix timestamp" }, "conversationDuration": { "type": "number", "description": "The duration of the conversation in seconds" }, "status": { "type": "string", "description": "The status of the conversation", "enum": [ "completed", "in_progress", "cancelled", "failed", "scheduled" ], "example": "completed" }, "agentName": { "type": "string", "description": "The name of the agent" }, "direction": { "type": "string", "description": "The direction of the conversation", "enum": [ "outbound", "inbound" ], "example": "outbound" }, "summary": { "type": "string", "description": "The summary of the conversation" }, "metadata": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the conversation was created" }, "createdBy": { "$ref": "#/components/schemas/MetaCreatedBy" } } } } }, "SuccessConversationListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationListItem" } }, "pagination": { "type": "object", "properties": { "pageSize": { "type": "integer", "description": "The number of items per page" }, "hasMore": { "type": "boolean", "description": "Indicates if there are more items to fetch" }, "nextCursor": { "type": "string", "nullable": true, "description": "The cursor to fetch the next page" } } } }, "description": "Paginated conversations with timing, status, and summary per row." }, "ConversationDetails": { "type": "object", "properties": { "agentId": { "type": "string", "description": "The ID of the agent" }, "agentName": { "type": "string", "description": "The name of the agent" }, "status": { "type": "string", "description": "The status of the conversation", "enum": [ "completed", "in_progress", "cancelled", "failed", "scheduled" ], "example": "completed" }, "direction": { "type": "string", "description": "The direction of the conversation", "enum": [ "outbound", "inbound" ], "example": "outbound" }, "conversationDuration": { "type": "number", "description": "Duration of the call in seconds." }, "startTimeUnix": { "type": "integer", "nullable": true, "description": "Call start time as a Unix timestamp in seconds." }, "endTimeUnix": { "type": "integer", "nullable": true, "description": "Call end time as a Unix timestamp in seconds." }, "summary": { "type": "string", "description": "AI-generated summary of the conversation." }, "transcript": { "type": "string", "description": "Full text transcript of the call." }, "contactNumber": { "type": "string", "description": "Phone number of the contact (the person called or calling in)." }, "callerNumber": { "type": "string", "description": "Phone number the call was placed from." }, "sentiment": { "type": "object", "description": "AI-analysed sentiment for the conversation.", "properties": { "sentiment_score": { "type": "number", "description": "The sentiment score of the conversation" }, "sentiment_by_turn": { "type": "array", "description": "The sentiment by turn of the conversation", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "The text of the sentiment" }, "sentiment_score": { "type": "number", "description": "The sentiment score of the sentiment" }, "sentiment_label": { "type": "string", "description": "The sentiment label of the sentiment" }, "speaker": { "type": "string", "description": "The speaker of the sentiment" } } } }, "sentiment_overall": { "type": "string", "description": "The overall sentiment of the conversation" } } }, "keyMoments": { "type": "array", "description": "Notable moments detected during the call such as objections or confirmations.", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "The text of the key moment" }, "label": { "type": "string", "description": "The label of the key moment" }, "speaker": { "type": "string", "description": "The speaker of the key moment" }, "timestamp": { "type": "string", "description": "The timestamp of the key moment" } } } }, "appointmentScheduled": { "type": "object", "additionalProperties": true, "description": "Appointment details if the agent scheduled one during the call." }, "dataCollected": { "type": "object", "description": "Structured data captured by the agent during the call.", "properties": { "entity": { "type": "string", "description": "The name of the extracted entity" }, "value": { "type": "string", "description": "The value of the extracted entity" } } }, "voiceMailDetected": { "type": "boolean", "description": "True if the call reached a voicemail instead of a live person." }, "errorMessage": { "type": "string", "description": "Error description if the call failed or ended unexpectedly." }, "callTransferred": { "type": "boolean", "description": "True if the call was transferred to a human agent." }, "metadata": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "The date and time the conversation was created" }, "createdBy": { "$ref": "#/components/schemas/MetaCreatedBy" } } } } }, "SuccessConversationDetailsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ConversationDetails" } }, "description": "Deep conversation record: transcript, sentiment, collected data, and metadata." }, "LanguagePreset": { "type": "object", "description": "Per-locale overrides for turn, TTS, conversation, and agent fields.", "properties": { "overrides": { "type": "object", "properties": { "turn": { "type": "object", "properties": { "softTimeoutConfig": { "type": "object", "properties": { "message": { "type": "string" } } } } }, "tts": { "type": "object", "properties": { "voiceId": { "type": "string" }, "stability": { "type": "number", "minimum": 0, "maximum": 1 }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.2 }, "similarityBoost": { "type": "number", "minimum": 0, "maximum": 1 } } }, "conversation": { "type": "object", "properties": { "textOnly": { "type": "boolean" } } }, "agent": { "type": "object", "properties": { "firstMessage": { "type": "string" }, "language": { "type": "string" }, "prompt": { "type": "object", "properties": { "prompt": { "type": "string" }, "llm": { "type": "string" } } } } } } } } }, "BuiltInToolCommon": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true }, "description": { "type": "string" }, "disableInterruption": { "type": "boolean", "default": false } } }, "CampaignContact": { "type": "object", "required": ["phoneNumber"], "properties": { "contactId": { "type": "string", "nullable": true }, "phoneNumber": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "additionalProperties": true }, "Campaign": { "type": "object", "properties": { "campaignId": { "type": "string" }, "name": { "type": "string" }, "agentId": { "type": "string" }, "active": { "type": "boolean" }, "scheduled": { "type": "boolean" }, "startTime": { "type": "string", "nullable": true }, "endTime": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "status": { "type": "string" }, "startIndex": { "type": "integer" }, "contactCount": { "type": "integer" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignContact" } }, "followUp": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "attempts": { "type": "integer" }, "intervalsMinutes": { "type": "array", "items": { "type": "integer" } } } }, "metadata": { "type": "object", "properties": { "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "deletedAt": { "type": "string", "nullable": true } } } } }, "CreateCampaignRequest": { "type": "object", "required": ["name", "agentId"], "properties": { "name": { "type": "string" }, "agentId": { "type": "string", "format": "uuid" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignContact" } }, "contactIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "active": { "type": "boolean", "default": true }, "scheduled": { "type": "boolean", "default": false }, "launch": { "type": "boolean", "default": false }, "startTime": { "type": "string" }, "endTime": { "type": "string" }, "timezone": { "type": "string", "example": "America/New_York" }, "followUpCall": { "type": "boolean", "default": false }, "followUpAttempts": { "type": "integer", "minimum": 1, "maximum": 10 }, "followUpIntervals": { "type": "array", "items": { "type": "integer" }, "description": "Delay in minutes before each follow-up. One value per attempt." } } }, "CreateCampaignCsvUpload": { "type": "object", "required": ["file", "name", "agentId"], "properties": { "file": { "type": "string", "format": "binary", "description": "UTF-8 .csv. Every phone number must be E.164." }, "name": { "type": "string" }, "agentId": { "type": "string", "format": "uuid" }, "launch": { "type": "boolean", "default": false }, "scheduled": { "type": "boolean", "default": false }, "startTime": { "type": "string" }, "endTime": { "type": "string" }, "timezone": { "type": "string" }, "phoneColumn": { "type": "string" }, "nameColumn": { "type": "string" }, "emailColumn": { "type": "string" }, "followUpCall": { "type": "boolean" }, "followUpAttempts": { "type": "integer" }, "followUpIntervals": { "type": "string", "description": "Comma-separated delays in minutes, one per follow-up attempt." } } }, "UpdateCampaignRequest": { "type": "object", "properties": { "name": { "type": "string" }, "agentId": { "type": "string", "format": "uuid" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignContact" } }, "contactIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "active": { "type": "boolean" }, "scheduled": { "type": "boolean" }, "startTime": { "type": "string", "nullable": true }, "endTime": { "type": "string", "nullable": true }, "timezone": { "type": "string", "nullable": true }, "followUpCall": { "type": "boolean" }, "followUpAttempts": { "type": "integer" }, "followUpIntervals": { "type": "array", "items": { "type": "integer" } } } }, "ScheduleCampaignRequest": { "type": "object", "properties": { "startTime": { "type": "string" }, "endTime": { "type": "string" }, "timezone": { "type": "string" } } }, "LaunchCampaignRequest": { "type": "object", "properties": { "startIndex": { "type": "integer", "minimum": 0 } } }, "SuccessCampaignResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Campaign" }, "warning": { "type": "string" }, "requestId": { "type": "string", "nullable": true } } }, "SuccessCampaignListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "pagination": { "type": "object", "properties": { "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } } }, "requestId": { "type": "string", "nullable": true } } }, "CampaignCall": { "type": "object", "properties": { "callId": { "type": "string" }, "campaignId": { "type": "string", "nullable": true }, "contactNumber": { "type": "string", "nullable": true }, "contactName": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "direction": { "type": "string", "nullable": true }, "durationSeconds": { "type": "integer", "nullable": true }, "followUpCount": { "type": "integer" }, "startedAt": { "type": "string", "nullable": true }, "endedAt": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "contact": { "type": "object", "nullable": true, "additionalProperties": true } } }, "SuccessCampaignCallListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignCall" } }, "pagination": { "type": "object", "properties": { "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } } }, "requestId": { "type": "string", "nullable": true } } }, "Contact": { "type": "object", "properties": { "contactId": { "type": "string" }, "phoneNumber": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "metadata": { "type": "object", "properties": { "createdAt": { "type": "string", "nullable": true } } } }, "additionalProperties": true }, "ContactWrite": { "type": "object", "properties": { "phoneNumber": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "additionalProperties": true }, "ContactCsvUpload": { "type": "object", "required": ["file"], "properties": { "file": { "type": "string", "format": "binary", "description": "UTF-8 .csv file, up to 10MB and 2000 data rows." }, "phoneColumn": { "type": "string", "description": "Header to use as the phone number when it is not named phone or phoneNumber." }, "nameColumn": { "type": "string" }, "emailColumn": { "type": "string" } } }, "ContactCsvRow": { "type": "object", "properties": { "row": { "type": "integer", "description": "Spreadsheet row number. The header is row 1." }, "status": { "type": "string", "enum": ["valid", "invalid", "duplicate", "existing"] }, "contact": { "$ref": "#/components/schemas/ContactWrite" }, "reasons": { "type": "array", "items": { "type": "string" } } } }, "ImportContactsRequest": { "type": "object", "required": ["contacts"], "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactWrite" } } } }, "DeleteContactsRequest": { "type": "object", "required": ["contactIds"], "properties": { "contactIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "SuccessContactResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Contact" }, "requestId": { "type": "string", "nullable": true } } }, "SuccessContactListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "pagination": { "type": "object", "properties": { "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } } }, "requestId": { "type": "string", "nullable": true } } }, "SuccessContactCsvVerifyResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "fileName": { "type": "string" }, "delimiter": { "type": "string", "enum": ["comma", "semicolon", "tab"] }, "headers": { "type": "array", "items": { "type": "string" } }, "mapping": { "type": "object", "properties": { "phoneNumber": { "type": "string" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } }, "summary": { "type": "object", "properties": { "rowCount": { "type": "integer" }, "validCount": { "type": "integer" }, "invalidCount": { "type": "integer" }, "duplicateCount": { "type": "integer" }, "existingCount": { "type": "integer" } } }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ContactCsvRow" } } } }, "requestId": { "type": "string", "nullable": true } } }, "SuccessContactCsvImportResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessContactCsvVerifyResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "created": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "skipped": { "type": "array", "items": { "type": "object" } }, "createdCount": { "type": "integer" }, "skippedCount": { "type": "integer" } } } } } ] }, "SuccessContactImportResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "created": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "phoneNumber": { "type": "string" }, "reason": { "type": "string" } } } }, "createdCount": { "type": "integer" }, "skippedCount": { "type": "integer" } } }, "requestId": { "type": "string", "nullable": true } } }, "SuccessContactDeleteResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "deletedCount": { "type": "integer" } } }, "requestId": { "type": "string", "nullable": true } } }, "SuccessContactDeleteOneResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "contactId": { "type": "string" }, "deleted": { "type": "boolean" } } }, "requestId": { "type": "string", "nullable": true } } }, "AgentTransfer": { "type": "object", "required": [ "agentId", "condition" ], "properties": { "agentId": { "type": "string" }, "condition": { "type": "string" }, "delayMs": { "type": "number" }, "transferMessage": { "type": "string" }, "enableTransferredAgentFirstMessage": { "type": "boolean" } } }, "HumanTransferDestination": { "type": "object", "required": [ "type", "phoneNumber" ], "properties": { "type": { "type": "string", "enum": [ "phone", "phone_dynamic_variable", "sip_uri", "sip_uri_dynamic_variable" ] }, "phoneNumber": { "type": "string" }, "sipUri": { "type": "string" } } }, "HumanTransfer": { "type": "object", "required": [ "transferType", "condition", "transferDestination" ], "properties": { "transferType": { "type": "string", "enum": [ "blind", "conference", "sip_refer" ] }, "condition": { "type": "string" }, "transferDestination": { "$ref": "#/components/schemas/HumanTransferDestination" } } }, "BuiltInTools": { "type": "object", "description": "Built-in system tools (PromptSchema.builtInTools).", "properties": { "endCall": { "$ref": "#/components/schemas/BuiltInToolCommon" }, "languageDetection": { "$ref": "#/components/schemas/BuiltInToolCommon" }, "skipTurn": { "$ref": "#/components/schemas/BuiltInToolCommon" }, "transferToAgent": { "allOf": [ { "$ref": "#/components/schemas/BuiltInToolCommon" }, { "type": "object", "properties": { "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTransfer" } } } } ] }, "transferToNumber": { "allOf": [ { "$ref": "#/components/schemas/BuiltInToolCommon" }, { "type": "object", "properties": { "transferRuleIds": { "type": "array", "items": { "type": "string" } }, "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/HumanTransfer" } } } } ] }, "voicemailDetection": { "allOf": [ { "$ref": "#/components/schemas/BuiltInToolCommon" }, { "type": "object", "properties": { "voicemailMessage": { "type": "string" } } } ] } } }, "AgentConversationConfiguration": { "type": "object", "required": [ "agent" ], "properties": { "asr": { "type": "object", "properties": { "userInputAudioFormat": { "type": "string", "default": "pcm_16000", "enum": [ "pcm_8000", "pcm_16000", "pcm_22050", "pcm_24000", "pcm_44100", "pcm_48000", "ulaw_8000" ], "description": "The format of the audio to be transcribed" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords to boost prediction probability for" } }, "description": "Configuration for conversational transcription" }, "turn": { "type": "object", "properties": { "turnTimeout": { "type": "number", "default": 7, "description": "Maximum wait time for the user\u2019s reply before re-engaging the user" }, "silenceEndCallTimeout": { "type": "number", "default": -1, "description": "Maximum wait time since the user last spoke before terminating the call" }, "turnEagerness": { "type": "string", "enum": [ "patient", "normal", "eager" ], "default": "normal", "description": "Controls how eager the agent is to respond. Low = less eager (waits longer), Standard = default eagerness, High = more eager (responds sooner)" }, "spellingPatience": { "type": "string", "enum": [ "auto", "off" ], "default": "auto", "description": "Controls if the agent should be more patient when user is spelling numbers and named entities. Auto = model based, Off = never wait extra" } }, "description": "Configuration for turn detection" }, "tts": { "type": "object", "properties": { "voiceId": { "type": "string", "description": "The voice ID to use for TTS", "default": "cjVigY5qzO86Huf0OWal" }, "supportedVoices": { "type": "array", "items": { "type": "object", "required": [ "label", "voiceId" ], "properties": { "label": { "type": "string" }, "voiceId": { "type": "string" }, "language": { "type": "string" }, "stability": { "type": "number", "minimum": 0, "maximum": 1 }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.2 }, "similarityBoost": { "type": "number", "minimum": 0, "maximum": 1 } } }, "description": "Additional supported voices for the agent" }, "expressiveMode": { "type": "boolean", "default": false, "description": "When enabled, applies expressive audio tags prompt." }, "suggestedAudioTags": { "type": "array", "items": { "type": "object", "required": [ "tag" ], "properties": { "tag": { "type": "string", "minLength": 1, "maxLength": 30 }, "description": { "type": "string", "maxLength": 200 } } }, "description": "Suggested audio tags to boost expressive speech. The agent can still use other tags not listed here." }, "agentOutputAudioFormat": { "type": "string", "default": "pcm_16000", "enum": [ "pcm_8000", "pcm_16000", "pcm_22050", "pcm_24000", "pcm_44100", "pcm_48000", "ulaw_8000" ], "description": "The audio format to use for TTS" }, "optimizeStreamingLatency": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ], "default": 3, "description": "Streaming latency optimization level (0\u20134)." }, "stability": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5, "description": "Controls the stability of the generated speech" }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.2, "default": 1, "description": "Controls the speed of the generated speech" }, "similarityBoost": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.8, "description": "The similarity boost for generated speech" } }, "description": "Configuration for conversational text to speech" }, "conversation": { "type": "object", "properties": { "maxDurationSeconds": { "type": "number", "default": 300, "description": "The maximum duration of the conversation in seconds" } }, "description": "Configuration for the conversation" }, "languagePresets": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/LanguagePreset" }, "description": "Per-locale preset overrides (record keyed by locale code)." }, "agent": { "type": "object", "required": [ "prompt" ], "properties": { "greetingMessage": { "type": "string", "description": "If non-empty, the first message the agent will say. If empty, the agent waits for the user to start the discussion." }, "primaryLanguage": { "type": "string", "default": "en", "description": "The primary language of the agent - used for ASR and TTS." }, "hinglishMode": { "type": "boolean", "default": false, "description": "When enabled, optimizes behavior for Hindi\u2013English (Hinglish) conversations." }, "dynamicVariables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Dynamic variable placeholders (string keys and string values)." }, "disableFirstMessageInterruptions": { "type": "boolean", "default": false, "description": "If true, the user will not be able to interrupt the agent while the first message is being delivered." }, "prompt": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "The prompt for the agent" }, "llm": { "type": "string", "enum": [ "gpt-oss-120b", "glm-45-air-fp8", "neuron-1.0", "gpt-4.1-nano", "gpt-5-nano", "gemini-2.5-flash-lite", "gemini-2.5-flash" ], "default": "gemini-2.5-flash", "description": "The LLM to query with the prompt and the chat history. If using data residency, the LLM must be supported in the data residency environment" }, "temperature": { "type": "number", "minimum": 0, "maximum": 1, "default": 0, "description": "The temperature for the LLM" }, "toolIds": { "type": "array", "items": { "type": "string" }, "description": "A list of IDs of tools used by the agent" }, "builtInTools": { "$ref": "#/components/schemas/BuiltInTools" }, "knowledgeBase": { "type": "array", "items": { "type": "string" }, "description": "A list of IDs of knowledge bases used by the agent" }, "ignoreDefaultPersonality": { "type": "boolean", "default": false, "description": "Whether to remove the default personality lines from the system prompt" }, "timezone": { "type": "string", "default": "UTC", "description": "Timezone for displaying current time in system prompt. If set, the current time will be included in the system prompt using this timezone. Must be a valid timezone name (e.g., \u2018America/New_York\u2019, \u2018Europe/London\u2019, \u2018UTC\u2019)." } }, "description": "The prompt for the agent" } }, "description": "Agent specific configuration" } } }, "UpdateAgentConversationConfiguration": { "type": "object", "properties": { "asr": { "type": "object", "properties": { "userInputAudioFormat": { "type": "string", "enum": [ "pcm_8000", "pcm_16000", "pcm_22050", "pcm_24000", "pcm_44100", "pcm_48000", "ulaw_8000" ], "description": "The format of the audio to be transcribed" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords to boost prediction probability for" } }, "description": "Configuration for conversational transcription" }, "turn": { "type": "object", "properties": { "turnTimeout": { "type": "number", "description": "Maximum wait time for the user\u2019s reply before re-engaging the user" }, "silenceEndCallTimeout": { "type": "number", "description": "Maximum wait time since the user last spoke before terminating the call" }, "turnEagerness": { "type": "string", "enum": [ "patient", "normal", "eager" ], "description": "Controls how eager the agent is to respond. Low = less eager (waits longer), Standard = default eagerness, High = more eager (responds sooner)" }, "spellingPatience": { "type": "string", "enum": [ "auto", "off" ], "description": "Controls if the agent should be more patient when user is spelling numbers and named entities. Auto = model based, Off = never wait extra" } }, "description": "Configuration for turn detection" }, "tts": { "type": "object", "properties": { "voiceId": { "type": "string", "description": "The voice ID to use for TTS" }, "supportedVoices": { "type": "array", "items": { "type": "object", "required": [ "label", "voiceId" ], "properties": { "label": { "type": "string" }, "voiceId": { "type": "string" }, "language": { "type": "string" }, "stability": { "type": "number", "minimum": 0, "maximum": 1 }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.2 }, "similarityBoost": { "type": "number", "minimum": 0, "maximum": 1 } } }, "description": "Additional supported voices for the agent" }, "expressiveMode": { "type": "boolean", "description": "When enabled, applies expressive audio tags prompt." }, "suggestedAudioTags": { "type": "array", "items": { "type": "object", "required": [ "tag" ], "properties": { "tag": { "type": "string", "minLength": 1, "maxLength": 30 }, "description": { "type": "string", "maxLength": 200 } } }, "description": "Suggested audio tags to boost expressive speech. The agent can still use other tags not listed here." }, "agentOutputAudioFormat": { "type": "string", "enum": [ "pcm_8000", "pcm_16000", "pcm_22050", "pcm_24000", "pcm_44100", "pcm_48000", "ulaw_8000" ], "description": "The audio format to use for TTS" }, "optimizeStreamingLatency": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ], "description": "Streaming latency optimization level (0\u20134)." }, "stability": { "type": "number", "minimum": 0, "maximum": 1, "description": "Controls the stability of the generated speech" }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.2, "description": "Controls the speed of the generated speech" }, "similarityBoost": { "type": "number", "minimum": 0, "maximum": 1, "description": "The similarity boost for generated speech" } }, "description": "Configuration for conversational text to speech" }, "conversation": { "type": "object", "properties": { "maxDurationSeconds": { "type": "number", "description": "The maximum duration of the conversation in seconds" } }, "description": "Configuration for the conversation" }, "languagePresets": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PatchLanguagePreset" }, "description": "Per-locale preset overrides (record keyed by locale code)." }, "agent": { "type": "object", "properties": { "greetingMessage": { "type": "string", "description": "If non-empty, the first message the agent will say. If empty, the agent waits for the user to start the discussion." }, "primaryLanguage": { "type": "string", "description": "The primary language of the agent - used for ASR and TTS." }, "hinglishMode": { "type": "boolean", "description": "When enabled, optimizes behavior for Hindi\u2013English (Hinglish) conversations." }, "dynamicVariables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Dynamic variable placeholders (string keys and string values)." }, "disableFirstMessageInterruptions": { "type": "boolean", "description": "If true, the user will not be able to interrupt the agent while the first message is being delivered." }, "prompt": { "type": "object", "properties": { "prompt": { "type": "string", "description": "The prompt for the agent" }, "llm": { "type": "string", "enum": [ "gpt-oss-120b", "glm-45-air-fp8", "neuron-1.0", "gpt-4.1-nano", "gpt-5-nano", "gemini-2.5-flash-lite", "gemini-2.5-flash" ], "description": "The LLM to query with the prompt and the chat history. If using data residency, the LLM must be supported in the data residency environment" }, "temperature": { "type": "number", "minimum": 0, "maximum": 1, "description": "The temperature for the LLM" }, "toolIds": { "type": "array", "items": { "type": "string" }, "description": "A list of IDs of tools used by the agent" }, "builtInTools": { "$ref": "#/components/schemas/PatchBuiltInTools" }, "knowledgeBase": { "type": "array", "items": { "type": "string" }, "description": "A list of IDs of knowledge bases used by the agent" }, "ignoreDefaultPersonality": { "type": "boolean", "description": "Whether to remove the default personality lines from the system prompt" }, "timezone": { "type": "string", "description": "Timezone for displaying current time in system prompt. If set, the current time will be included in the system prompt using this timezone. Must be a valid timezone name (e.g., \u2018America/New_York\u2019, \u2018Europe/London\u2019, \u2018UTC\u2019)." } }, "description": "The prompt for the agent" } }, "description": "Agent specific configuration" } } }, "DataCollectionEntity": { "type": "object", "required": [ "type", "description" ], "properties": { "type": { "type": "string", "enum": [ "boolean", "string", "number", "integer" ], "description": "JSON-compatible type for the collected field." }, "description": { "type": "string", "description": "What this entity represents." }, "enum": { "type": "array", "items": { "type": "string" }, "description": "Optional allowed values (for string-like fields)." } } }, "AgentPlatformSettings": { "type": "object", "properties": { "callActions": { "type": "object", "properties": { "smartOptOut": { "type": "boolean", "default": false, "description": "Whether to enable smart opt-out" }, "issueTracking": { "type": "boolean", "default": false, "description": "Whether to enable issue tracking" }, "postCallWebhook": { "type": "string", "description": "The URL to send the post-call webhook to" }, "postCallEmail": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "emailConfiguration": { "type": "object", "additionalProperties": { "type": "string" } } }, "description": "Configuration for the post-call email" }, "scheduleOnCalendar": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "provider": { "type": "string", "enum": [ "google", "calcom" ] }, "eventsIds": { "type": "array", "items": { "type": "string" } } }, "description": "Configuration for the schedule on calendar" } }, "description": "Call actions settings" }, "widget": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Widget configuration as string key/value pairs." }, "dataCollection": { "type": "object", "properties": { "entities": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataCollectionEntity" }, "description": "Named entities to extract (entity name \u2192 schema)." }, "storeData": { "type": "boolean", "default": false } }, "description": "Data collection settings" }, "callRetry": { "type": "object", "properties": { "retryCount": { "type": "integer", "description": "The number of times to retry the call" }, "retryDelay": { "type": "integer", "description": "The delay in seconds between retries" } }, "description": "Call retry settings" }, "summaryLanguage": { "type": "string", "description": "Language for all conversation analysis outputs (summaries, titles, evaluation rationales, data collection rationales). If not set, the language will be inferred from the conversation. Must be one of the supported conversation languages." }, "privacy": { "type": "object", "properties": { "recordVoice": { "type": "boolean", "default": false, "description": "Whether to record the voice of the caller" } }, "description": "Privacy settings for the agent" }, "telephony": { "type": "object", "properties": { "numberRotationEnabled": { "type": "boolean", "default": false, "description": "Whether to enable number rotation" }, "rotationNumbers": { "type": "array", "items": { "type": "string" }, "description": "The numbers to rotate through" }, "callsPerNumber": { "type": "integer", "description": "The number of calls to make per number" }, "stateRestrictionEnabled": { "type": "boolean", "default": false, "description": "Whether to enable state restriction" }, "stateRestrictedNumbers": { "type": "array", "items": { "type": "string" }, "description": "The numbers to restrict the agent to" } }, "description": "Telephony settings for the agent" } }, "description": "The platform settings of the agent" }, "PaginationMeta": { "type": "object", "properties": { "pageSize": { "type": "integer", "description": "How many items to return at maximum. Can not exceed 100, defaults to 30." }, "hasMore": { "type": "boolean", "description": "Indicates if there are more items to fetch." }, "nextCursor": { "type": "string", "nullable": true, "description": "Used for fetching next page. Cursor is returned in the response." }, "sortBy": { "type": "string", "description": "The field to sort the results by.", "example": "name" }, "sortDirection": { "type": "string", "enum": [ "asc", "desc" ], "description": "The direction to sort the results.", "example": "asc" } } }, "DocumentUrlDetails": { "type": "object", "description": "Type-specific payload when `type` is `url` (no file fields).", "additionalProperties": false, "properties": { "url": { "type": "string", "description": "The source URL of the document." } } }, "DocumentFileDetails": { "type": "object", "description": "Type-specific payload when `type` is `file` (no source URL).", "additionalProperties": false, "properties": { "fileUrl": { "type": "string", "description": "Public URL of the stored file." }, "fileType": { "type": "string", "description": "MIME type of the file (e.g. `application/pdf`, `text/plain`)." }, "fileSize": { "type": "number", "description": "File size in bytes." } } }, "DocumentDetailsUrl": { "type": "object", "description": "URL-sourced document. `details` holds only `url`; file fields live only on file documents.", "additionalProperties": false, "properties": { "documentId": { "type": "string", "description": "The ID of the document." }, "type": { "type": "string", "enum": [ "url" ], "description": "Discriminator: URL document." }, "name": { "type": "string", "description": "The display name of the document." }, "details": { "$ref": "#/components/schemas/DocumentUrlDetails" }, "metadata": { "type": "object", "description": "Optional server metadata.", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "When the document was created." }, "createdBy": { "$ref": "#/components/schemas/MetaCreatedBy" } } } } }, "DocumentDetailsFile": { "type": "object", "description": "Uploaded file document. `details` holds storage URL, MIME type, and size; display name is `name`.", "additionalProperties": false, "properties": { "documentId": { "type": "string", "description": "The ID of the document." }, "type": { "type": "string", "enum": [ "file" ], "description": "Discriminator: uploaded file document." }, "name": { "type": "string", "description": "Display name (often the original file name)." }, "details": { "$ref": "#/components/schemas/DocumentFileDetails" }, "metadata": { "type": "object", "description": "Optional server metadata.", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "When the document was created." }, "createdBy": { "$ref": "#/components/schemas/MetaCreatedBy" } } } } }, "DocumentDetails": { "oneOf": [ { "$ref": "#/components/schemas/DocumentDetailsUrl" }, { "$ref": "#/components/schemas/DocumentDetailsFile" } ], "discriminator": { "propertyName": "type", "mapping": { "url": "#/components/schemas/DocumentDetailsUrl", "file": "#/components/schemas/DocumentDetailsFile" } } }, "GroupDetails": { "type": "object", "properties": { "groupId": { "type": "string", "description": "The ID of the group" }, "name": { "type": "string", "description": "The name of the group" }, "documents": { "type": "array", "description": "A list of documents in the group", "items": { "$ref": "#/components/schemas/DocumentDetails" } }, "metadata": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the group was created" }, "createdBy": { "$ref": "#/components/schemas/MetaCreatedBy" } } } } }, "GroupUpdateDetails": { "type": "object", "properties": { "groupId": { "type": "string", "description": "The ID of the group" }, "name": { "type": "string", "description": "The name of the group" }, "metadata": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the group was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time the group was updated" }, "createdBy": { "$ref": "#/components/schemas/MetaCreatedBy" } } } } }, "SuccessDocumentListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "A list of documents and their metadata", "type": "array", "items": { "$ref": "#/components/schemas/DocumentDetails" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "description": "Paginated knowledge documents (URL and file types)." }, "SuccessDocumentDetailsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "Document details; shape depends on `type` (`url` vs `file`).", "$ref": "#/components/schemas/DocumentDetails" } }, "description": "One knowledge document; shape of `data` depends on `type` (`url` vs `file`)." }, "SuccessDocumentUrlCreateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/DocumentDetailsUrl" } }, "description": "New URL-based document added to the knowledge base." }, "SuccessGroupDetailsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "The details of the group", "$ref": "#/components/schemas/GroupDetails" } }, "description": "A knowledge group with its documents and metadata." }, "SuccessGroupUpdateDetailsResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "The details of the group", "$ref": "#/components/schemas/GroupUpdateDetails" } }, "description": "Group after a rename or metadata update." }, "SuccessGroupListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "A list of groups and their metadata", "type": "array", "items": { "$ref": "#/components/schemas/GroupDetails" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "description": "Paginated knowledge groups." }, "CreateDocumentFromUrlRequest": { "type": "object", "description": "Add a knowledge document by pointing at a public web page. The agent can use this content during calls.", "required": [ "url", "name" ], "properties": { "url": { "type": "string", "description": "URL to a page of documentation that the agent will have access to in order to interact with users." }, "name": { "type": "string", "description": "A custom, human-readable name for the document." } } }, "CreateDocumentFromFileRequest": { "type": "object", "description": "Upload one or more files into a knowledge group (`multipart/form-data`). The group is created or matched by `groupName`.", "required": [ "groupName", "files" ], "properties": { "groupName": { "type": "string", "description": "Name of the knowledge group to create or add these documents to." }, "files": { "type": "array", "minItems": 1, "description": "Files to upload. Each file must be **PDF** (`.pdf`), **Word** (`.docx`), or **TSX** (`.tsx`). **Maximum 5 MB** per file.", "items": { "type": "string", "format": "binary", "description": "One file: PDF, DOCX, or TSX; max 5 MB." } } } }, "UpdateGroupRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "A custom, human-readable name for the group." } } }, "SuccessDocumentCreateFromFileResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "description": "The details of the document created", "type": "object", "properties": { "groupId": { "type": "string", "description": "The ID of the group created" }, "name": { "type": "string", "description": "The name of the group" }, "documents": { "type": "array", "description": "Created file documents. Each item uses nested `details` (`fileUrl`, `fileType`, `fileSize`); no `url` at the document root.", "items": { "$ref": "#/components/schemas/DocumentDetailsFile" } }, "metadata": { "type": "object", "description": "Knowledge-base storage usage in MB (no audit fields).", "properties": { "allowedMb": { "type": "number", "description": "The allowed size of the document in MB" }, "usedMb": { "type": "number", "description": "The used size of the document in MB" }, "usedMbAfter": { "type": "number", "description": "The used size of the document in MB after the document was created" }, "remainingMbAfter": { "type": "number", "description": "The remaining size of the document in MB after the document was created" } } } } } }, "description": "After uploading files: new or updated group, created documents, and storage usage (MB)." }, "PatchAgentPlatformSettings": { "type": "object", "properties": { "callActions": { "type": "object", "properties": { "smartOptOut": { "type": "boolean", "description": "Whether to enable smart opt-out" }, "issueTracking": { "type": "boolean", "description": "Whether to enable issue tracking" }, "postCallWebhook": { "type": "string", "description": "The URL to send the post-call webhook to" }, "postCallEmail": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "emailConfiguration": { "type": "object", "additionalProperties": { "type": "string" } } }, "description": "Configuration for the post-call email" }, "scheduleOnCalendar": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "google", "calcom" ] }, "eventsIds": { "type": "array", "items": { "type": "string" } } }, "description": "Configuration for the schedule on calendar" } }, "description": "Call actions settings" }, "widget": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Widget configuration as string key/value pairs." }, "dataCollection": { "type": "object", "properties": { "entities": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PatchDataCollectionEntity" }, "description": "Named entities to extract (entity name \u2192 schema)." }, "storeData": { "type": "boolean" } }, "description": "Data collection settings" }, "callRetry": { "type": "object", "properties": { "retryCount": { "type": "integer", "description": "The number of times to retry the call" }, "retryDelay": { "type": "integer", "description": "The delay in seconds between retries" } }, "description": "Call retry settings" }, "summaryLanguage": { "type": "string", "description": "Language for all conversation analysis outputs (summaries, titles, evaluation rationales, data collection rationales). If not set, the language will be inferred from the conversation. Must be one of the supported conversation languages." }, "privacy": { "type": "object", "properties": { "recordVoice": { "type": "boolean", "description": "Whether to record the voice of the caller" } }, "description": "Privacy settings for the agent" }, "telephony": { "type": "object", "properties": { "numberRotationEnabled": { "type": "boolean", "description": "Whether to enable number rotation" }, "rotationNumbers": { "type": "array", "items": { "type": "string" }, "description": "The numbers to rotate through" }, "callsPerNumber": { "type": "integer", "description": "The number of calls to make per number" }, "stateRestrictionEnabled": { "type": "boolean", "description": "Whether to enable state restriction" }, "stateRestrictedNumbers": { "type": "array", "items": { "type": "string" }, "description": "The numbers to restrict the agent to" } }, "description": "Telephony settings for the agent" } }, "description": "Platform settings fields to update. Only include fields you want to change." }, "PatchDataCollectionEntity": { "type": "object", "required": [ "type", "description" ], "properties": { "type": { "type": "string", "enum": [ "boolean", "string", "number", "integer" ], "description": "JSON-compatible type for the collected field." }, "description": { "type": "string", "description": "What this entity represents." }, "enum": { "type": "array", "items": { "type": "string" }, "description": "Optional allowed values (for string-like fields)." } } }, "PatchHumanTransferDestination": { "type": "object", "required": [ "type", "phoneNumber" ], "properties": { "type": { "type": "string", "enum": [ "phone", "phone_dynamic_variable", "sip_uri", "sip_uri_dynamic_variable" ] }, "phoneNumber": { "type": "string" }, "sipUri": { "type": "string" } } }, "PatchBuiltInToolCommon": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "description": { "type": "string" }, "disableInterruption": { "type": "boolean" } } }, "PatchHumanTransfer": { "type": "object", "required": [ "transferType", "condition", "transferDestination" ], "properties": { "transferType": { "type": "string", "enum": [ "blind", "conference", "sip_refer" ] }, "condition": { "type": "string" }, "transferDestination": { "$ref": "#/components/schemas/PatchHumanTransferDestination" } } }, "PatchLanguagePreset": { "type": "object", "description": "Per-locale overrides for turn, TTS, conversation, and agent fields.", "properties": { "overrides": { "type": "object", "properties": { "turn": { "type": "object", "properties": { "softTimeoutConfig": { "type": "object", "properties": { "message": { "type": "string" } } } } }, "tts": { "type": "object", "properties": { "voiceId": { "type": "string" }, "stability": { "type": "number", "minimum": 0, "maximum": 1 }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.2 }, "similarityBoost": { "type": "number", "minimum": 0, "maximum": 1 } } }, "conversation": { "type": "object", "properties": { "textOnly": { "type": "boolean" } } }, "agent": { "type": "object", "properties": { "firstMessage": { "type": "string" }, "language": { "type": "string" }, "prompt": { "type": "object", "properties": { "prompt": { "type": "string" }, "llm": { "type": "string" } } } } } } } } }, "PatchBuiltInTools": { "type": "object", "description": "Built-in system tools (PromptSchema.builtInTools).", "properties": { "endCall": { "$ref": "#/components/schemas/PatchBuiltInToolCommon" }, "languageDetection": { "$ref": "#/components/schemas/PatchBuiltInToolCommon" }, "skipTurn": { "$ref": "#/components/schemas/PatchBuiltInToolCommon" }, "transferToAgent": { "allOf": [ { "$ref": "#/components/schemas/PatchBuiltInToolCommon" }, { "type": "object", "properties": { "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/PatchAgentTransfer" } } } } ] }, "transferToNumber": { "allOf": [ { "$ref": "#/components/schemas/PatchBuiltInToolCommon" }, { "type": "object", "properties": { "transferRuleIds": { "type": "array", "items": { "type": "string" } }, "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/PatchHumanTransfer" } } } } ] }, "voicemailDetection": { "allOf": [ { "$ref": "#/components/schemas/PatchBuiltInToolCommon" }, { "type": "object", "properties": { "voicemailMessage": { "type": "string" } } } ] } } }, "PatchAgentTransfer": { "type": "object", "required": [ "agentId", "condition" ], "properties": { "agentId": { "type": "string" }, "condition": { "type": "string" }, "delayMs": { "type": "number" }, "transferMessage": { "type": "string" }, "enableTransferredAgentFirstMessage": { "type": "boolean" } } } } } }