{ "openapi": "3.1.0", "info": { "title": "Assistable v3 API", "version": "3.0.0", "description": "Scoped, rate-limited public API. Authenticate with a Bearer API key (ask_live_…). Select the target subaccount via the X-Subaccount-Id header." }, "servers": [ { "url": "https://api.assistable.ai", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "components": { "schemas": { "Assistant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "temperature": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assistantType": { "type": "string" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voiceEnabled": { "type": "boolean" }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "model", "prompt", "temperature", "voiceId", "assistantType", "language", "voiceEnabled", "folderId", "archived", "createdAt", "updatedAt" ], "additionalProperties": false }, "AssistantVersion": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "number" }, "prompt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changeNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "version", "prompt", "changeNote", "createdAt" ], "additionalProperties": false }, "AssistantNote": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "author": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "content", "author", "createdAt" ], "additionalProperties": false }, "Voice": { "type": "object", "properties": { "id": { "type": "string" }, "voiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voiceName": { "type": "string" }, "provider": { "type": "string" }, "accent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "age": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "previewAudioUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isCustom": { "type": "boolean" }, "ownerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "voiceId", "voiceName", "provider", "accent", "gender", "age", "previewAudioUrl", "isCustom", "ownerId" ], "additionalProperties": false }, "VoiceFilterOptions": { "type": "object", "properties": { "providers": { "type": "array", "items": { "type": "string" } }, "genders": { "type": "array", "items": { "type": "string" } }, "ages": { "type": "array", "items": { "type": "string" } }, "accents": { "type": "array", "items": { "type": "string" } } }, "required": [ "providers", "genders", "ages", "accents" ], "additionalProperties": false }, "VoiceStats": { "type": "object", "properties": { "totalVoices": { "type": "number" }, "systemVoices": { "type": "number" }, "customVoices": { "type": "number" }, "byProvider": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } } }, "required": [ "totalVoices", "systemVoices", "customVoices", "byProvider" ], "additionalProperties": false }, "AssistantFolder": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isArchived": { "type": "boolean" }, "counts": { "type": "object", "properties": { "total": { "type": "number" }, "archived": { "type": "number" } }, "required": [ "total", "archived" ], "additionalProperties": false } }, "required": [ "id", "name", "color", "isArchived", "counts" ], "additionalProperties": false }, "Contact": { "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "companyName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkedinUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "locationText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dnd": { "type": "boolean" }, "isArchived": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "contactId", "name", "firstName", "lastName", "email", "phone", "title", "companyName", "image", "website", "linkedinUrl", "locationText", "source", "status", "dnd", "isArchived", "createdAt", "updatedAt" ], "additionalProperties": false }, "ContactNote": { "type": "object", "properties": { "id": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "value", "createdBy", "createdAt", "updatedAt" ], "additionalProperties": false }, "Tag": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tagId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assistantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "tagId", "assistantId", "createdAt" ], "additionalProperties": false }, "PhoneNumber": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "number": { "type": "string" }, "type": { "type": "string" }, "sipUri": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assistantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assistantName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "callerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "callingUri": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "answerWaitTime": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "hdVoiceEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "isLegacy": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "number", "type", "sipUri", "assistantId", "assistantName", "folderId", "callerId", "callingUri", "answerWaitTime", "hdVoiceEnabled", "isLegacy", "createdAt", "updatedAt" ], "additionalProperties": false }, "NumberPool": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phoneNumbersCount": { "type": "number" }, "phoneNumbers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "number", "name" ], "additionalProperties": false } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "phoneNumbersCount", "phoneNumbers", "createdAt", "updatedAt" ], "additionalProperties": false }, "Appointment": { "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assistantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startTimeDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "contactId", "contactName", "address", "status", "source", "assistantId", "startTime", "endTime", "startTimeDate", "createdAt" ], "additionalProperties": false }, "Tool": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "toolType": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "httpMethod": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isPrebuilt": { "type": "boolean" }, "subAccountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "category", "toolType", "url", "httpMethod", "isPrebuilt", "subAccountId", "createdAt", "updatedAt" ], "additionalProperties": false }, "KnowledgeBase": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voiceEnabled": { "type": "boolean" }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sources": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "voiceEnabled", "folderId", "sources", "createdAt", "updatedAt" ], "additionalProperties": false }, "KnowledgeSource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "type", "status", "createdAt" ], "additionalProperties": false }, "QueryTraining": { "type": "object", "properties": { "id": { "type": "string" }, "knowledgeBaseId": { "type": "string" }, "query": { "type": "string" }, "response": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "knowledgeBaseId", "query", "response", "isActive", "createdAt", "updatedAt" ], "additionalProperties": false }, "Conversation": { "type": "object", "properties": { "id": { "type": "string" }, "contactId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "previewText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastChannel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "conversationType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "aiResponses": { "type": "number" }, "isArchived": { "type": "boolean" }, "isFavorite": { "type": "boolean" }, "leadQuality": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userSentiment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assistant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "contactId", "contactName", "contactEmail", "contactPhone", "previewText", "lastChannel", "conversationType", "aiResponses", "isArchived", "isFavorite", "leadQuality", "userSentiment", "status", "summary", "assistant", "createdAt", "updatedAt" ], "additionalProperties": false }, "ConversationStats": { "type": "object", "properties": { "total": { "type": "number" }, "archived": { "type": "number" }, "active": { "type": "number" }, "totalMessages": { "type": "number" }, "aiMessages": { "type": "number" } }, "required": [ "total", "archived", "active", "totalMessages", "aiMessages" ], "additionalProperties": false }, "CallListItem": { "type": "object", "properties": { "id": { "type": "string" }, "callId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "callStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "callType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "direction": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "toNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fromNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalDurationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "costInDollars": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "disconnectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userSentiment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "callSummary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recordingUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assistantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startTimestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "contact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "assistant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "callId", "callStatus", "callType", "direction", "toNumber", "fromNumber", "durationMs", "totalDurationSeconds", "costInDollars", "disconnectionReason", "userSentiment", "callSummary", "recordingUrl", "assistantId", "contactId", "startTimestamp", "createdAt", "contact", "assistant" ], "additionalProperties": false }, "CallStats": { "type": "object", "properties": { "totalCalls": { "type": "number" }, "completedCalls": { "type": "number" }, "errorCalls": { "type": "number" }, "totalDurationMinutes": { "type": "number" }, "avgDurationSeconds": { "type": "number" }, "totalCost": { "type": "string" }, "totalRevenue": { "type": "string" }, "sentimentBreakdown": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } } }, "required": [ "totalCalls", "completedCalls", "errorCalls", "totalDurationMinutes", "avgDurationSeconds", "totalCost", "totalRevenue", "sentimentBreakdown" ], "additionalProperties": false }, "Call": { "type": "object", "properties": { "id": { "type": "string" }, "callId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "callStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "callType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "direction": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "toNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fromNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalDurationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "costInDollars": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "disconnectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userSentiment": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "callSummary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recordingUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assistantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startTimestamp": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "contact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "assistant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "transcript": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "conversationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "callControlId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "callSessionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "disposition": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transcriptObject": { "anyOf": [ {}, { "type": "null" } ] }, "callAnalysis": { "anyOf": [ {}, { "type": "null" } ] }, "latencyAverages": { "anyOf": [ {}, { "type": "null" } ] }, "calledTools": { "anyOf": [ {}, { "type": "null" } ] }, "callCost": { "anyOf": [ {}, { "type": "null" } ] }, "variables": { "anyOf": [ {}, { "type": "null" } ] }, "callLegs": { "anyOf": [ {}, { "type": "null" } ] }, "recordingUrls": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "id", "callId", "callStatus", "callType", "direction", "toNumber", "fromNumber", "durationMs", "totalDurationSeconds", "costInDollars", "disconnectionReason", "userSentiment", "callSummary", "recordingUrl", "assistantId", "contactId", "startTimestamp", "createdAt", "contact", "assistant", "transcript", "conversationId", "callControlId", "callSessionId", "disposition", "transcriptObject", "callAnalysis", "latencyAverages", "calledTools", "callCost", "variables", "callLegs", "recordingUrls" ], "additionalProperties": false }, "Alert": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string", "enum": [ "COMPLIANCE", "QUALITY", "SAFETY", "ESCALATION", "CUSTOM" ], "description": "Alert category: COMPLIANCE, QUALITY, SAFETY, ESCALATION, or CUSTOM." }, "status": { "type": "string", "enum": [ "OPEN", "ACKNOWLEDGED", "RESOLVED", "DISMISSED" ], "description": "Resolution status: OPEN, ACKNOWLEDGED, RESOLVED, or DISMISSED." }, "severity": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Severity: LOW, MEDIUM, HIGH, or CRITICAL." }, "triggered": { "type": "boolean" }, "assistantId": { "type": "string" }, "subAccountId": { "type": "string" }, "monitorRuleId": { "type": "string" }, "ruleName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "callId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "conversationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contact": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "phone" ], "additionalProperties": false }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "evalTimeMs": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "transcript": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "extractedData": { "anyOf": [ {}, { "type": "null" } ] }, "toolCalls": { "anyOf": [ {}, { "type": "null" } ] }, "evaluatorOutput": { "anyOf": [ {}, { "type": "null" } ] }, "resolutionNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resolvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "category", "status", "severity", "triggered", "assistantId", "subAccountId", "monitorRuleId", "ruleName", "callId", "conversationId", "contact", "reason", "evalTimeMs", "transcript", "extractedData", "toolCalls", "evaluatorOutput", "resolutionNote", "resolvedAt", "createdAt" ], "additionalProperties": false }, "MonitorRule": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "type": "string", "enum": [ "COMPLIANCE", "QUALITY", "SAFETY", "ESCALATION", "CUSTOM" ], "description": "Alert category: COMPLIANCE, QUALITY, SAFETY, ESCALATION, or CUSTOM." }, "triggerOn": { "type": "string", "enum": [ "CALL", "CHAT", "BOTH" ], "description": "Which interactions a rule evaluates: CALL, CHAT, or BOTH." }, "evaluatorPrompt": { "type": "string" }, "severity": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Severity: LOW, MEDIUM, HIGH, or CRITICAL." }, "threshold": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "thresholdWindowMins": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cooldownMins": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enabled": { "type": "boolean" }, "isPrebuilt": { "type": "boolean" }, "assistantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subAccountId": { "type": "string" }, "channels": { "type": "array", "items": { "$ref": "#/components/schemas/AlertChannel" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "category", "triggerOn", "evaluatorPrompt", "severity", "threshold", "thresholdWindowMins", "cooldownMins", "enabled", "isPrebuilt", "assistantId", "subAccountId", "channels", "createdAt", "updatedAt" ], "additionalProperties": false }, "AlertChannel": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "WEBHOOK", "EMAIL", "SLACK" ], "description": "Routing channel type: WEBHOOK, EMAIL, or SLACK." }, "config": {}, "minSeverity": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Severity: LOW, MEDIUM, HIGH, or CRITICAL." }, "enabled": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "userId", "externalEmail" ], "additionalProperties": false } } }, "required": [ "id", "type", "config", "minSeverity", "enabled", "recipients" ], "additionalProperties": false }, "SubAccount": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "integrationType": { "type": "string" }, "integrationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "locationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "webhookUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "webhookSecret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Signing secret for the Direct inbound webhook listener. Returned ONCE in the create response — store it then; it is always null on list and get and cannot be retrieved again." }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "integrationType", "integrationId", "locationId", "webhookUrl", "webhookSecret", "createdAt" ], "additionalProperties": false }, "SubAccountUser": { "type": "object", "properties": { "userId": { "type": "string" }, "subAccountId": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "created": { "type": "boolean", "description": "true if a new user was created; false if an existing user was linked." } }, "required": [ "userId", "subAccountId", "email", "role", "created" ], "additionalProperties": false }, "SubAccountMember": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "userId", "email", "name", "role", "createdAt" ], "additionalProperties": false }, "SubAccountWallet": { "type": "object", "properties": { "subAccountId": { "type": "string" }, "subAccountBalanceCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "subAccountBalanceDollars": { "type": "number" }, "workspaceBalanceCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "workspaceBalanceDollars": { "type": "number" } }, "required": [ "subAccountId", "subAccountBalanceCents", "subAccountBalanceDollars", "workspaceBalanceCents", "workspaceBalanceDollars" ], "additionalProperties": false }, "SubAccountWalletMutation": { "type": "object", "properties": { "subAccountId": { "type": "string" }, "target": { "type": "string", "enum": [ "workspace", "subaccount" ] }, "direction": { "type": "string", "enum": [ "credit", "debit" ] }, "amountCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balanceCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balanceDollars": { "type": "number" }, "replayed": { "type": "boolean", "description": "True when an idempotency_key replay returned the original result without moving funds again." } }, "required": [ "subAccountId", "target", "direction", "amountCents", "balanceCents", "balanceDollars", "replayed" ], "additionalProperties": false }, "ApiError": { "type": "object", "properties": { "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ] }, "SubAccountMemberRole": { "type": "object", "properties": { "userId": { "type": "string" }, "subAccountId": { "type": "string" }, "role": { "type": "string" } }, "required": [ "userId", "subAccountId", "role" ], "additionalProperties": false } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your v3 API key, e.g. `ask_live_…`" } } }, "paths": { "/v3/assistants": { "get": { "summary": "List assistants", "operationId": "listAssistants", "tags": [ "Assistants" ], "description": "Requires scope `assistants:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Assistant" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Max rows to return (1–100, default 50).", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "description": "Include archived assistants in the list (default false).", "type": "boolean" } } ] }, "post": { "summary": "Create an assistant", "operationId": "createAssistant", "tags": [ "Assistants" ], "description": "Requires scope `assistants:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Assistant" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name for the assistant." }, "description": { "type": "string" }, "prompt": { "description": "System prompt. If omitted, a minimal default prompt is generated from the name.", "type": "string" }, "model": { "description": "LLM model. Defaults to KIMI_K2_5 when omitted.", "type": "string", "enum": [ "QWEN_3_235B_A22B", "GPT_5_4", "GPT_5_2", "GPT_5_1", "GPT_5", "GPT_5_MINI", "GPT_5_NANO", "GPT_4_1", "GPT_4_1_MINI", "GPT_4_1_NANO", "GPT_4O", "GPT_4O_MINI", "GPT_4_TURBO", "GPT_4", "GPT_3_5_TURBO", "CLAUDE_4_1_OPUS", "CLAUDE_4_SONNET", "CLAUDE_3_7_SONNET", "CLAUDE_HAIKU_4_5", "CLAUDE_3_5_HAIKU", "CLAUDE_3_SONNET", "CLAUDE_3_HAIKU", "GEMINI_2_5_FLASH", "GEMINI_2_0_FLASH", "GEMINI_2_0_FLASH_LITE", "KIMI_K2_5", "KIMI_K2_6", "CUSTOM" ] }, "temperature": { "description": "Sampling temperature 0–2 (default 0).", "type": "number", "minimum": 0, "maximum": 2 }, "voice_id": { "description": "Voice PK (the `id` from GET /v3/voices). Defaults to the system default voice when omitted.", "type": "string" }, "assistant_type": { "type": "string", "enum": [ "STANDARD", "FLOW_BUILDER" ], "description": "Assistant type. STANDARD (default) is a prompt-driven assistant; FLOW_BUILDER is node/flow driven." }, "language": { "description": "BCP-47 language code (default 'en').", "type": "string" }, "voice_enabled": { "description": "Whether voice calling is enabled (default true).", "type": "boolean" }, "inbound_greeting": { "type": "string" }, "outbound_greeting": { "type": "string" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/v3/assistants/{id}": { "get": { "summary": "Get an assistant", "operationId": "getAssistant", "tags": [ "Assistants" ], "description": "Requires scope `assistants:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Assistant" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "summary": "Update an assistant", "operationId": "updateAssistant", "tags": [ "Assistants" ], "description": "Requires scope `assistants:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Assistant" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "prompt": { "type": "string" }, "model": { "type": "string", "enum": [ "QWEN_3_235B_A22B", "GPT_5_4", "GPT_5_2", "GPT_5_1", "GPT_5", "GPT_5_MINI", "GPT_5_NANO", "GPT_4_1", "GPT_4_1_MINI", "GPT_4_1_NANO", "GPT_4O", "GPT_4O_MINI", "GPT_4_TURBO", "GPT_4", "GPT_3_5_TURBO", "CLAUDE_4_1_OPUS", "CLAUDE_4_SONNET", "CLAUDE_3_7_SONNET", "CLAUDE_HAIKU_4_5", "CLAUDE_3_5_HAIKU", "CLAUDE_3_SONNET", "CLAUDE_3_HAIKU", "GEMINI_2_5_FLASH", "GEMINI_2_0_FLASH", "GEMINI_2_0_FLASH_LITE", "KIMI_K2_5", "KIMI_K2_6", "CUSTOM" ], "description": "LLM model, one of the AIModel enum values (e.g. KIMI_K2_5 — the default, GPT_5, CLAUDE_4_SONNET, GEMINI_2_5_FLASH). Resolved to the provider model at agent-sync time." }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "voice_id": { "type": "string" }, "assistant_type": { "type": "string", "enum": [ "STANDARD", "FLOW_BUILDER" ], "description": "Assistant type. STANDARD (default) is a prompt-driven assistant; FLOW_BUILDER is node/flow driven." }, "language": { "type": "string" }, "voice_enabled": { "type": "boolean" }, "inbound_greeting": { "type": "string" }, "outbound_greeting": { "type": "string" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } }, "delete": { "summary": "Delete (soft) an assistant", "operationId": "deleteAssistant", "tags": [ "Assistants" ], "description": "Requires scope `assistants:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/assistants/{id}/archive": { "post": { "summary": "Archive an assistant", "operationId": "archiveAssistant", "tags": [ "Assistants" ], "description": "Requires scope `assistants:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/assistants/{id}/unarchive": { "post": { "summary": "Unarchive an assistant", "operationId": "unarchiveAssistant", "tags": [ "Assistants" ], "description": "Requires scope `assistants:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/assistants/{id}/duplicate": { "post": { "summary": "Duplicate an assistant", "operationId": "duplicateAssistant", "tags": [ "Assistants" ], "description": "Requires scope `assistants:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Assistant" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/assistants/{id}/versions": { "get": { "summary": "List assistant versions", "operationId": "listAssistantVersions", "tags": [ "Assistants" ], "description": "Requires scope `assistants:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantVersion" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/assistants/{id}/versions/{version_id}/revert": { "post": { "summary": "Revert an assistant to a version", "operationId": "revertAssistantVersion", "tags": [ "Assistants" ], "description": "Requires scope `assistants:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Assistant" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/assistants/{id}/notes": { "get": { "summary": "List assistant notes", "operationId": "listAssistantNotes", "tags": [ "Assistants" ], "description": "Requires scope `assistants:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantNote" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "post": { "summary": "Add a note to an assistant", "operationId": "createAssistantNote", "tags": [ "Assistants" ], "description": "Requires scope `assistants:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AssistantNote" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Plain-text note body (max 2000 chars)." }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "content" ], "additionalProperties": false } } } } } }, "/v3/assistants/{id}/notes/{note_id}": { "delete": { "summary": "Delete an assistant note", "operationId": "deleteAssistantNote", "tags": [ "Assistants" ], "description": "Requires scope `assistants:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "note_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/voices": { "get": { "summary": "List voices", "operationId": "listVoices", "tags": [ "Voices" ], "description": "Requires scope `voices:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Voice" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "description": "Match on name / voiceId / accent.", "type": "string" } }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ELEVENLABS", "OPENAI", "DEEPGRAM", "PLAYHT", "CUSTOM", "RIME", "MINIMAX", "ENSEMBLE", "TELNYX", "AZURE", "AWS", "INWORLD", "RESEMBLE", "XAI" ], "description": "Voice provider (e.g. ELEVENLABS, RIME, OPENAI)." } }, { "name": "gender", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "MALE", "FEMALE", "NEUTRAL" ], "description": "Voice gender filter." } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ] } }, "/v3/voices/filter-options": { "get": { "summary": "Distinct voice filter options", "operationId": "getVoiceFilterOptions", "tags": [ "Voices" ], "description": "Requires scope `voices:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VoiceFilterOptions" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ] } }, "/v3/voices/stats": { "get": { "summary": "Voice library stats", "operationId": "getVoiceStats", "tags": [ "Voices" ], "description": "Requires scope `voices:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VoiceStats" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ] } }, "/v3/voices/{id}": { "get": { "summary": "Get a voice", "operationId": "getVoice", "tags": [ "Voices" ], "description": "Requires scope `voices:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Voice" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/voices/{id}/allow-copy": { "patch": { "summary": "Toggle whether a custom voice can be copied", "operationId": "updateVoiceAllowCopy", "tags": [ "Voices" ], "description": "Requires scope `voices:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Voice" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allow_copy": { "type": "boolean" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "allow_copy" ], "additionalProperties": false } } } } } }, "/v3/assistant-folders": { "get": { "summary": "List assistant folders", "operationId": "listAssistantFolders", "tags": [ "Assistant folders" ], "description": "Requires scope `assistants:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssistantFolder" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean" } } ] }, "post": { "summary": "Create an assistant folder", "operationId": "createAssistantFolder", "tags": [ "Assistant folders" ], "description": "Requires scope `assistants:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AssistantFolder" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "color": { "description": "Optional hex color for the folder.", "type": "string" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/v3/assistant-folders/{id}": { "patch": { "summary": "Update an assistant folder", "operationId": "updateAssistantFolder", "tags": [ "Assistant folders" ], "description": "Requires scope `assistants:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AssistantFolder" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "color": { "type": "string" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } }, "delete": { "summary": "Delete (archive) an assistant folder", "operationId": "deleteAssistantFolder", "tags": [ "Assistant folders" ], "description": "Requires scope `assistants:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/assistant-folders/{id}/assign": { "post": { "summary": "Assign assistants to a folder", "operationId": "assignAssistantsToFolder", "tags": [ "Assistant folders" ], "description": "Requires scope `assistants:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_ids": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Assistant ids to assign to (or remove from) the folder." }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "assistant_ids" ], "additionalProperties": false } } } } } }, "/v3/assistant-folders/{id}/remove": { "post": { "summary": "Remove assistants from a folder", "operationId": "removeAssistantsFromFolder", "tags": [ "Assistant folders" ], "description": "Requires scope `assistants:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_ids": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Assistant ids to assign to (or remove from) the folder." }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "assistant_ids" ], "additionalProperties": false } } } } } }, "/v3/contacts": { "get": { "summary": "List contacts", "operationId": "listContacts", "tags": [ "Contacts" ], "description": "Requires scope `contacts:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "search", "in": "query", "required": false, "schema": { "description": "Match on name / email / phone.", "type": "string" } } ] }, "post": { "summary": "Create a contact", "operationId": "createContact", "tags": [ "Contacts" ], "description": "Requires scope `contacts:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "const": "" } ] }, "phone": { "type": "string" }, "title": { "type": "string" }, "company_name": { "type": "string" }, "image": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "dnd": { "type": "boolean" }, "language": { "type": "string" }, "timezone": { "type": "string" }, "website": { "type": "string" }, "linkedin_url": { "type": "string" }, "location_text": { "type": "string" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } } }, "/v3/contacts/{id}": { "get": { "summary": "Get a contact", "operationId": "getContact", "tags": [ "Contacts" ], "description": "Requires scope `contacts:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "summary": "Update a contact", "operationId": "updateContact", "tags": [ "Contacts" ], "description": "Requires scope `contacts:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string" }, "email": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "string", "const": "" } ] }, "phone": { "type": "string" }, "title": { "type": "string" }, "company_name": { "type": "string" }, "image": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "dnd": { "type": "boolean" }, "language": { "type": "string" }, "timezone": { "type": "string" }, "website": { "type": "string" }, "linkedin_url": { "type": "string" }, "location_text": { "type": "string" }, "is_archived": { "type": "boolean" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } }, "delete": { "summary": "Delete (archive) a contact", "operationId": "deleteContact", "tags": [ "Contacts" ], "description": "Requires scope `contacts:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/contacts/{id}/permanent-delete": { "post": { "summary": "Permanently delete a contact", "operationId": "permanentlyDeleteContact", "tags": [ "Contacts" ], "description": "Requires scope `contacts:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/contacts/{id}/notes": { "get": { "summary": "List contact notes", "operationId": "listContactNotes", "tags": [ "Contacts" ], "description": "Requires scope `contacts:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactNote" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "post": { "summary": "Add a note to a contact", "operationId": "createContactNote", "tags": [ "Contacts" ], "description": "Requires scope `contacts:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactNote" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 8000 }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "value" ], "additionalProperties": false } } } } } }, "/v3/contacts/{id}/notes/{note_id}": { "delete": { "summary": "Delete a contact note", "operationId": "deleteContactNote", "tags": [ "Contacts" ], "description": "Requires scope `contacts:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "note_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/contacts/{id}/interactions": { "get": { "summary": "List contact interactions", "operationId": "listContactInteractions", "tags": [ "Contacts" ], "description": "Requires scope `contacts:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/tags": { "get": { "summary": "List tags", "operationId": "listTags", "tags": [ "Tags" ], "description": "Requires scope `tags:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "assistant_id", "in": "query", "required": false, "schema": { "description": "Filter to tags linked to this assistant.", "type": "string" } } ] }, "post": { "summary": "Create a tag", "operationId": "createTag", "tags": [ "Tags" ], "description": "Requires scope `tags:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "assistant_id": { "type": "string" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/v3/tags/{id}": { "get": { "summary": "Get a tag", "operationId": "getTag", "tags": [ "Tags" ], "description": "Requires scope `tags:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "summary": "Update a tag", "operationId": "updateTag", "tags": [ "Tags" ], "description": "Requires scope `tags:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tag" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "assistant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } }, "delete": { "summary": "Delete a tag", "operationId": "deleteTag", "tags": [ "Tags" ], "description": "Requires scope `tags:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/tags/{id}/permanent-delete": { "post": { "summary": "Permanently delete a tag", "operationId": "permanentlyDeleteTag", "tags": [ "Tags" ], "description": "Requires scope `tags:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/phone-numbers": { "get": { "summary": "List owned phone numbers", "operationId": "listPhoneNumbers", "tags": [ "Phone numbers" ], "description": "Requires scope `numbers:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ] } }, "/v3/phone-numbers/{id}": { "get": { "summary": "Get a phone number", "operationId": "getPhoneNumber", "tags": [ "Phone numbers" ], "description": "Requires scope `numbers:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhoneNumber" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "summary": "Update a phone number", "operationId": "updatePhoneNumber", "tags": [ "Phone numbers" ], "description": "Requires scope `numbers:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhoneNumber" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "caller_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sip_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "calling_uri": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "answer_wait_time": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 300 }, { "type": "null" } ] }, "hd_voice_enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } } }, "/v3/phone-numbers/{id}/assign": { "post": { "summary": "Assign a phone number to an assistant", "operationId": "assignPhoneNumber", "tags": [ "Phone numbers" ], "description": "Requires scope `numbers:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PhoneNumber" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Assistant to bind, or null to unassign." }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "assistant_id" ], "additionalProperties": false } } } } } }, "/v3/number-pools": { "get": { "summary": "List number pools", "operationId": "listNumberPools", "tags": [ "Number pools" ], "description": "Requires scope `numbers:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NumberPool" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ] }, "post": { "summary": "Create a number pool", "operationId": "createNumberPool", "tags": [ "Number pools" ], "description": "Requires scope `numbers:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NumberPool" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "phone_number_ids": { "type": "array", "items": { "type": "string" } }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } } }, "/v3/number-pools/{id}": { "get": { "summary": "Get a number pool", "operationId": "getNumberPool", "tags": [ "Number pools" ], "description": "Requires scope `numbers:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NumberPool" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "summary": "Update a number pool", "operationId": "updateNumberPool", "tags": [ "Number pools" ], "description": "Requires scope `numbers:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NumberPool" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } }, "delete": { "summary": "Delete a number pool", "operationId": "deleteNumberPool", "tags": [ "Number pools" ], "description": "Requires scope `numbers:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/number-pools/{id}/add-numbers": { "post": { "summary": "Add phone numbers to a pool", "operationId": "addNumbersToPool", "tags": [ "Number pools" ], "description": "Requires scope `numbers:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NumberPool" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number_ids": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "phone_number_ids" ], "additionalProperties": false } } } } } }, "/v3/number-pools/{id}/remove-numbers": { "post": { "summary": "Remove phone numbers from a pool", "operationId": "removeNumbersFromPool", "tags": [ "Number pools" ], "description": "Requires scope `numbers:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NumberPool" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number_ids": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "phone_number_ids" ], "additionalProperties": false } } } } } }, "/v3/appointments": { "get": { "summary": "List appointments in a date range", "operationId": "listAppointments", "tags": [ "Appointments" ], "description": "Requires scope `appointments:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Appointment" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Range start (ISO datetime)." } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Range end (ISO datetime)." } } ] }, "post": { "summary": "Create an appointment", "operationId": "createAppointment", "tags": [ "Appointments" ], "description": "Requires scope `appointments:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Appointment" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_name": { "type": "string" }, "start_time": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Appointment start (ISO datetime)." }, "end_time": { "type": "string" }, "address": { "type": "string" }, "status": { "type": "string", "enum": [ "SCHEDULED", "CONFIRMED", "CANCELLED", "COMPLETED", "NO_SHOW", "RESCHEDULED" ], "description": "Appointment status: SCHEDULED, CONFIRMED, CANCELLED, COMPLETED, NO_SHOW, RESCHEDULED." }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "start_time" ], "additionalProperties": false } } } } } }, "/v3/appointments/{id}": { "get": { "summary": "Get an appointment", "operationId": "getAppointment", "tags": [ "Appointments" ], "description": "Requires scope `appointments:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Appointment" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "summary": "Update an appointment", "operationId": "updateAppointment", "tags": [ "Appointments" ], "description": "Requires scope `appointments:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Appointment" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "start_time": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "end_time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "SCHEDULED", "CONFIRMED", "CANCELLED", "COMPLETED", "NO_SHOW", "RESCHEDULED" ], "description": "Appointment status: SCHEDULED, CONFIRMED, CANCELLED, COMPLETED, NO_SHOW, RESCHEDULED." }, { "type": "null" } ] }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } } }, "/v3/tools": { "get": { "summary": "List tools", "operationId": "listTools", "tags": [ "Tools" ], "description": "Requires scope `tools:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "tool_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "FUNCTION", "CUSTOM", "END_CALL", "PRESS_DIGIT", "TRANSFER_CALL" ], "description": "Tool type. FUNCTION (chat/LLM, default) or CUSTOM (voice tool with URL); END_CALL/PRESS_DIGIT/TRANSFER_CALL are builtins." } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "include_prebuilt", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "deprecated", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "assistant_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ] }, "post": { "summary": "Create a tool", "operationId": "createTool", "tags": [ "Tools" ], "description": "Requires scope `tools:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tool" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" }, "description": { "type": "string" }, "category": { "type": "string" }, "tool_type": { "type": "string", "enum": [ "FUNCTION", "CUSTOM", "END_CALL", "PRESS_DIGIT", "TRANSFER_CALL" ], "description": "Tool type. FUNCTION (chat/LLM, default) or CUSTOM (voice tool with URL); END_CALL/PRESS_DIGIT/TRANSFER_CALL are builtins." }, "url": { "type": "string", "format": "uri" }, "http_method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "description": "HTTP method for the tool's endpoint (default POST)." }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "parameters": { "description": "JSON Schema object describing the tool's parameters.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "required_params": { "type": "array", "items": { "type": "string" } }, "speak_during_execution": { "type": "boolean" }, "speak_after_execution": { "type": "boolean" }, "execution_message_description": { "type": "string" }, "transfer_prompt": { "type": "string" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/v3/tools/categories": { "get": { "summary": "List distinct tool categories", "operationId": "listToolCategories", "tags": [ "Tools" ], "description": "Requires scope `tools:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ] } }, "/v3/tools/{id}": { "get": { "summary": "Get a tool (with parameters + headers)", "operationId": "getTool", "tags": [ "Tools" ], "description": "Requires scope `tools:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tool" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "summary": "Update a tool", "operationId": "updateTool", "tags": [ "Tools" ], "description": "Requires scope `tools:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tool" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" }, "description": { "type": "string" }, "category": { "type": "string" }, "tool_type": { "type": "string", "enum": [ "FUNCTION", "CUSTOM", "END_CALL", "PRESS_DIGIT", "TRANSFER_CALL" ], "description": "Tool type. FUNCTION (chat/LLM, default) or CUSTOM (voice tool with URL); END_CALL/PRESS_DIGIT/TRANSFER_CALL are builtins." }, "url": { "type": "string", "format": "uri" }, "http_method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "description": "HTTP method for the tool's endpoint (default POST)." }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "parameters": { "description": "JSON Schema object describing the tool's parameters.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "required_params": { "type": "array", "items": { "type": "string" } }, "speak_during_execution": { "type": "boolean" }, "speak_after_execution": { "type": "boolean" }, "execution_message_description": { "type": "string" }, "transfer_prompt": { "type": "string" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } }, "delete": { "summary": "Delete (soft) a tool", "operationId": "deleteTool", "tags": [ "Tools" ], "description": "Requires scope `tools:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/tools/{id}/copy": { "post": { "summary": "Copy a tool into this subaccount", "operationId": "copyTool", "tags": [ "Tools" ], "description": "Requires scope `tools:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Tool" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/tools/{id}/assign": { "post": { "summary": "Assign a tool to an assistant", "operationId": "assignTool", "tags": [ "Tools" ], "description": "Requires scope `tools:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_id": { "type": "string", "minLength": 1 }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "assistant_id" ], "additionalProperties": false } } } } } }, "/v3/tools/{id}/remove": { "post": { "summary": "Remove a tool from an assistant", "operationId": "removeTool", "tags": [ "Tools" ], "description": "Requires scope `tools:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_id": { "type": "string", "minLength": 1 }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "assistant_id" ], "additionalProperties": false } } } } } }, "/v3/assistants/{id}/tools": { "get": { "summary": "List an assistant's tools", "operationId": "listAssistantTools", "tags": [ "Tools" ], "description": "Requires scope `tools:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/knowledge-bases": { "get": { "summary": "List knowledge bases", "operationId": "listKnowledgeBases", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBase" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "required": false, "schema": { "description": "Match on knowledge base name.", "type": "string" } } ] }, "post": { "summary": "Create a knowledge base", "operationId": "createKnowledgeBase", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeBase" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "folder_id": { "type": "string" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/v3/knowledge-bases/{id}": { "get": { "summary": "Get a knowledge base (with sources)", "operationId": "getKnowledgeBase", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeBase" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "summary": "Update a knowledge base", "operationId": "updateKnowledgeBase", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeBase" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "folder_id": { "type": "string" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } }, "delete": { "summary": "Archive a knowledge base", "operationId": "archiveKnowledgeBase", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/knowledge-bases/{id}/sources/text": { "post": { "summary": "Add a text source", "operationId": "createTextSource", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeSource" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "text": { "type": "string", "minLength": 1 }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "name", "text" ], "additionalProperties": false } } } } } }, "/v3/knowledge-bases/{id}/sources/faq": { "post": { "summary": "Add an FAQ source", "operationId": "createFaqSource", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeSource" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "faqs": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1 }, "answer": { "type": "string", "minLength": 1 } }, "required": [ "question", "answer" ], "additionalProperties": false } }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "name", "faqs" ], "additionalProperties": false } } } } } }, "/v3/knowledge-bases/{id}/sources/url": { "post": { "summary": "Add a URL source", "operationId": "createUrlSource", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeSource" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "name", "url" ], "additionalProperties": false } } } } } }, "/v3/knowledge-bases/{id}/sources/file": { "post": { "summary": "Add a file source", "operationId": "createFileSource", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeSource" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "file_url": { "type": "string", "format": "uri" }, "filename": { "type": "string", "minLength": 1 }, "file_size": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mime_type": { "type": "string" }, "use_unstructured_api": { "type": "boolean" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "name", "file_url", "filename" ], "additionalProperties": false } } } } } }, "/v3/knowledge-bases/{id}/sources/{source_id}": { "patch": { "summary": "Rename a source", "operationId": "renameKnowledgeSource", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeSource" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } } } }, "delete": { "summary": "Delete a source", "operationId": "deleteKnowledgeSource", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/knowledge-bases/{id}/query-trainings": { "get": { "summary": "List query trainings", "operationId": "listQueryTrainings", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/QueryTraining" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean" } } ] }, "post": { "summary": "Create a query training", "operationId": "createQueryTraining", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QueryTraining" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "response": { "type": "string", "minLength": 1 }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "query", "response" ], "additionalProperties": false } } } } } }, "/v3/knowledge-bases/{id}/query-trainings/{training_id}": { "patch": { "summary": "Update a query training", "operationId": "updateQueryTraining", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QueryTraining" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "training_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "response": { "type": "string", "minLength": 1 }, "is_active": { "type": "boolean" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } }, "delete": { "summary": "Delete a query training", "operationId": "deleteQueryTraining", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "training_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/knowledge-bases/{id}/query-trainings/{training_id}/toggle": { "post": { "summary": "Toggle a query training active flag", "operationId": "toggleQueryTraining", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/QueryTraining" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "training_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/knowledge-bases/{id}/assign": { "post": { "summary": "Assign a knowledge base to an assistant", "operationId": "assignKnowledgeBase", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_id": { "type": "string", "minLength": 1 }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "assistant_id" ], "additionalProperties": false } } } } } }, "/v3/knowledge-bases/{id}/remove": { "post": { "summary": "Remove a knowledge base from an assistant", "operationId": "removeKnowledgeBase", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_id": { "type": "string", "minLength": 1 }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "assistant_id" ], "additionalProperties": false } } } } } }, "/v3/knowledge-bases/{id}/voice/enable": { "post": { "summary": "Enable voice for a knowledge base", "operationId": "enableKnowledgeBaseVoice", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/knowledge-bases/{id}/voice/disable": { "post": { "summary": "Disable voice for a knowledge base", "operationId": "disableKnowledgeBaseVoice", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/assistants/{id}/knowledge-bases": { "get": { "summary": "List an assistant's knowledge base ids", "operationId": "listAssistantKnowledgeBases", "tags": [ "Knowledge base" ], "description": "Requires scope `knowledge:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBase" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/conversations": { "get": { "summary": "List conversations", "operationId": "listConversations", "tags": [ "Conversations" ], "description": "Requires scope `conversations:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "next_cursor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_count": { "type": "number" } }, "required": [ "conversations", "next_cursor", "total_count" ], "additionalProperties": false }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Offset for pagination (the `next_cursor` from a prior page).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "search", "in": "query", "required": false, "schema": { "description": "Match on contact name/email/phone or conversation preview.", "type": "string" } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "SMS", "EMAIL", "VOICE", "WHATSAPP", "WEBCHAT", "FACEBOOK", "INSTAGRAM", "GMB", "LIVE_CHAT", "CUSTOM" ], "description": "Conversation channel (e.g. SMS, EMAIL, VOICE, WHATSAPP, WEBCHAT)." } }, { "name": "is_archived", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "is_favorite", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "schema": { "description": "Sort order (default newest).", "type": "string", "enum": [ "newest", "oldest", "most_active" ] } } ] } }, "/v3/conversations/stats": { "get": { "summary": "Conversation stats for the subaccount", "operationId": "getConversationStats", "tags": [ "Conversations" ], "description": "Requires scope `conversations:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversationStats" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ] } }, "/v3/conversations/{id}": { "get": { "summary": "Get a conversation", "operationId": "getConversation", "tags": [ "Conversations" ], "description": "Requires scope `conversations:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "summary": "Update a conversation", "operationId": "updateConversation", "tags": [ "Conversations" ], "description": "Requires scope `conversations:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "summary": { "anyOf": [ { "type": "string", "maxLength": 8000 }, { "type": "null" } ] }, "is_archived": { "type": "boolean" }, "is_favorite": { "type": "boolean" }, "lead_quality": { "anyOf": [ { "type": "string", "enum": [ "HOT", "WARM", "COLD", "UNQUALIFIED" ], "description": "Lead quality: HOT, WARM, COLD, or UNQUALIFIED." }, { "type": "null" } ] }, "user_sentiment": { "anyOf": [ { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "MIXED" ], "description": "User sentiment: POSITIVE, NEUTRAL, NEGATIVE, or MIXED." }, { "type": "null" } ] }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } }, "delete": { "summary": "Delete (soft) a conversation", "operationId": "deleteConversation", "tags": [ "Conversations" ], "description": "Requires scope `conversations:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/conversations/{id}/calls": { "get": { "summary": "List calls for a conversation", "operationId": "listConversationCalls", "tags": [ "Conversations" ], "description": "Requires scope `conversations:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CallListItem" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Upstream provider error (call_failed / chat_failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/conversations/{id}/messages": { "get": { "summary": "List messages in a conversation", "operationId": "listConversationMessages", "tags": [ "Messages" ], "description": "Requires scope `messages:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/messages": { "post": { "summary": "Create a message", "operationId": "createMessage", "tags": [ "Messages" ], "description": "Requires scope `messages:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "conversation_id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1, "maxLength": 8000 }, "channel": { "description": "Defaults to the conversation's last channel, else CUSTOM.", "type": "string", "enum": [ "SMS", "EMAIL", "VOICE", "WHATSAPP", "WEBCHAT", "FACEBOOK", "INSTAGRAM", "GMB", "LIVE_CHAT", "CUSTOM" ] }, "type": { "type": "string", "enum": [ "TEXT", "IMAGE", "VIDEO", "AUDIO", "FILE", "LOCATION", "CONTACT", "SYSTEM", "TOOL_CALL", "TOOL_RESULT", "FUNCTION_CALL", "FUNCTION_RESULT" ], "description": "Message type. Defaults to TEXT." }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "conversation_id", "content" ], "additionalProperties": false } } } } } }, "/v3/chat/completions": { "post": { "summary": "Run an AI chat completion on a conversation", "operationId": "createChatCompletion", "tags": [ "Chat" ], "description": "Requires scope `chat:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Upstream provider error (call_failed / chat_failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_id": { "type": "string", "minLength": 1 }, "conversation_id": { "type": "string", "minLength": 1 }, "additional_instructions": { "type": "string" }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "assistant_id", "conversation_id" ], "additionalProperties": false } } } } } }, "/v3/calls": { "post": { "summary": "Place an AI voice call", "operationId": "createCall", "tags": [ "Calls" ], "description": "Requires scope `calls:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Upstream provider error (call_failed / chat_failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assistant_id": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "from": { "type": "string" }, "contact_id": { "type": "string" }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "assistant_id", "to" ], "additionalProperties": false } } } } }, "get": { "summary": "List call history", "operationId": "listCalls", "tags": [ "Calls" ], "description": "Requires scope `calls:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "calls": { "type": "array", "items": { "$ref": "#/components/schemas/CallListItem" } }, "page": { "type": "number" }, "limit": { "type": "number" }, "total_records": { "type": "number" }, "total_pages": { "type": "number" } }, "required": [ "calls", "page", "limit", "total_records", "total_pages" ], "additionalProperties": false }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Upstream provider error (call_failed / chat_failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "search", "in": "query", "required": false, "schema": { "description": "Match on to/from number, callId, or contact name/email.", "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "QUEUED", "INITIATED", "RINGING", "IN_PROGRESS", "COMPLETED", "BUSY", "FAILED", "NO_ANSWER", "CANCELED" ], "description": "Call status: QUEUED, INITIATED, RINGING, IN_PROGRESS, COMPLETED, BUSY, FAILED, NO_ANSWER, CANCELED." } }, { "name": "sentiment", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "MIXED" ], "description": "User sentiment: POSITIVE, NEUTRAL, NEGATIVE, or MIXED." } }, { "name": "min_duration_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "max_duration_seconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "start_date", "in": "query", "required": false, "schema": { "description": "ISO datetime — include calls created at/after this instant.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "description": "ISO datetime — include calls created at/before this instant.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } } ] } }, "/v3/calls/stats": { "get": { "summary": "Call stats for the subaccount", "operationId": "getCallStats", "tags": [ "Calls" ], "description": "Requires scope `calls:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CallStats" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Upstream provider error (call_failed / chat_failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } } ] } }, "/v3/calls/{id}": { "get": { "summary": "Get a call (rich detail)", "operationId": "getCall", "tags": [ "Calls" ], "description": "Requires scope `calls:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Call" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Upstream provider error (call_failed / chat_failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/flows": { "post": { "summary": "Create a flow", "operationId": "createFlow", "tags": [ "Flows" ], "description": "Requires scope `flows:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "flow_id": { "type": "string", "minLength": 1 }, "api_response": {}, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "name", "flow_id" ], "additionalProperties": false } } } } } }, "/v3/alerts": { "get": { "summary": "List alerts", "operationId": "listAlerts", "tags": [ "Alerts" ], "description": "Requires scope `alerts:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Max rows to return (1–100, default 50).", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Filter by resolution status.", "type": "string", "enum": [ "OPEN", "ACKNOWLEDGED", "RESOLVED", "DISMISSED" ] } }, { "name": "assistant_id", "in": "query", "required": false, "schema": { "description": "Filter by assistant id.", "type": "string" } }, { "name": "monitor_rule_id", "in": "query", "required": false, "schema": { "description": "Filter by the rule that produced the alert.", "type": "string" } }, { "name": "contact_id", "in": "query", "required": false, "schema": { "description": "Filter by local contact id (observations created after ASSIST-420).", "type": "string" } }, { "name": "ghl_contact_id", "in": "query", "required": false, "schema": { "description": "Filter by GoHighLevel contact id (observations created after ASSIST-420).", "type": "string" } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "COMPLIANCE", "QUALITY", "SAFETY", "ESCALATION", "CUSTOM" ], "description": "Alert category: COMPLIANCE, QUALITY, SAFETY, ESCALATION, or CUSTOM." } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Severity: LOW, MEDIUM, HIGH, or CRITICAL." } }, { "name": "triggered", "in": "query", "required": false, "schema": { "description": "Filter by whether the rule actually triggered. Defaults to true (only triggered alerts).", "type": "boolean" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "description": "ISO-8601 lower bound on creation time (inclusive).", "type": "string" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "description": "ISO-8601 upper bound on creation time (inclusive).", "type": "string" } } ] } }, "/v3/alerts/{id}": { "get": { "summary": "Get an alert", "operationId": "getAlert", "tags": [ "Alerts" ], "description": "Requires scope `alerts:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Alert" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "summary": "Update an alert's resolution status or note", "operationId": "updateAlert", "tags": [ "Alerts" ], "description": "Requires scope `alerts:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Alert" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "New resolution status: OPEN, ACKNOWLEDGED, RESOLVED, or DISMISSED.", "type": "string", "enum": [ "OPEN", "ACKNOWLEDGED", "RESOLVED", "DISMISSED" ] }, "resolution_note": { "description": "Free-text note stored with the resolution.", "type": "string", "maxLength": 5000 }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } } }, "/v3/monitor-rules": { "get": { "summary": "List monitor rules", "operationId": "listMonitorRules", "tags": [ "Monitor Rules" ], "description": "Requires scope `monitor-rules:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorRule" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "Max rows to return (1–100, default 50).", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "assistant_id", "in": "query", "required": false, "schema": { "description": "Filter to rules scoped to this assistant (omit for subaccount-wide rules).", "type": "string" } }, { "name": "enabled", "in": "query", "required": false, "schema": { "description": "Filter by enabled state.", "type": "boolean" } } ] }, "post": { "summary": "Create a monitor rule", "operationId": "createMonitorRule", "tags": [ "Monitor Rules" ], "description": "Requires scope `monitor-rules:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MonitorRule" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Human-readable rule name." }, "description": { "description": "What this rule is for.", "type": "string", "maxLength": 2000 }, "evaluator_prompt": { "type": "string", "minLength": 1, "description": "What to watch for — the instruction the LLM evaluator runs against each transcript." }, "category": { "description": "Defaults to CUSTOM.", "type": "string", "enum": [ "COMPLIANCE", "QUALITY", "SAFETY", "ESCALATION", "CUSTOM" ] }, "trigger_on": { "description": "Which interactions to evaluate. Defaults to BOTH.", "type": "string", "enum": [ "CALL", "CHAT", "BOTH" ] }, "severity": { "description": "Defaults to MEDIUM.", "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ] }, "assistant_id": { "description": "Scope the rule to a single assistant. Omit for a subaccount-wide rule.", "type": "string" }, "threshold": { "description": "Triggers required within the window before alerting. Default 1.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "threshold_window_mins": { "description": "Rolling window (minutes) for the threshold count. Default 0 (alert on every trigger).", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cooldown_mins": { "description": "Minimum minutes between alerts for this rule. Default 0.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "enabled": { "description": "Defaults to true.", "type": "boolean" }, "routing": { "description": "Alert routing channels (webhook/email/slack) with recipients.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "WEBHOOK", "EMAIL", "SLACK" ], "description": "Routing channel type: WEBHOOK, EMAIL, or SLACK." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Channel-specific config — e.g. { url } for WEBHOOK, { channel } for SLACK." }, "min_severity": { "description": "Only route alerts at or above this severity. Default LOW.", "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ] }, "enabled": { "type": "boolean" }, "recipients": { "description": "Recipients for EMAIL/SLACK channels.", "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "additionalProperties": false } } }, "required": [ "type", "config" ], "additionalProperties": false } }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "required": [ "name", "evaluator_prompt" ], "additionalProperties": false } } } } } }, "/v3/monitor-rules/{id}": { "get": { "summary": "Get a monitor rule", "operationId": "getMonitorRule", "tags": [ "Monitor Rules" ], "description": "Requires scope `monitor-rules:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MonitorRule" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "summary": "Update a monitor rule", "operationId": "updateMonitorRule", "tags": [ "Monitor Rules" ], "description": "Requires scope `monitor-rules:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MonitorRule" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Alternatively pass `subaccount_id` (or legacy `location_id`) in the request body. Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "evaluator_prompt": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": [ "COMPLIANCE", "QUALITY", "SAFETY", "ESCALATION", "CUSTOM" ], "description": "Alert category: COMPLIANCE, QUALITY, SAFETY, ESCALATION, or CUSTOM." }, "trigger_on": { "type": "string", "enum": [ "CALL", "CHAT", "BOTH" ], "description": "Which interactions a rule evaluates: CALL, CHAT, or BOTH." }, "severity": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "Severity: LOW, MEDIUM, HIGH, or CRITICAL." }, "threshold": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "threshold_window_mins": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cooldown_mins": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "enabled": { "type": "boolean" }, "routing": { "description": "If provided, REPLACES all existing routing channels for the rule.", "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "WEBHOOK", "EMAIL", "SLACK" ], "description": "Routing channel type: WEBHOOK, EMAIL, or SLACK." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Channel-specific config — e.g. { url } for WEBHOOK, { channel } for SLACK." }, "min_severity": { "description": "Only route alerts at or above this severity. Default LOW.", "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ] }, "enabled": { "type": "boolean" }, "recipients": { "description": "Recipients for EMAIL/SLACK channels.", "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "additionalProperties": false } } }, "required": [ "type", "config" ], "additionalProperties": false } }, "subaccount_id": { "description": "Target subaccount id. Prefer the X-Subaccount-Id header; this body field is a fallback.", "type": "string" }, "location_id": { "description": "Alias for subaccount_id (GHL location id).", "type": "string" } }, "additionalProperties": false } } } } }, "delete": { "summary": "Delete a monitor rule", "operationId": "deleteMonitorRule", "tags": [ "Monitor Rules" ], "description": "Requires scope `monitor-rules:delete`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "X-Subaccount-Id", "in": "header", "required": false, "description": "Target subaccount for the request. Required unless the API key is authorized for exactly one subaccount (then it defaults to that one). Omitting it on a multi-subaccount key returns `400 subaccount_required`.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/subaccounts": { "post": { "summary": "Create a subaccount — Assistable Direct (name), or provision from a GoHighLevel Location ID (location_id)", "operationId": "createSubaccount", "tags": [ "Subaccounts" ], "description": "Requires scope `subaccounts:create`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubAccount" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Display name for a new Assistable Direct (CRM-free) subaccount. Provide EITHER name OR location_id, not both.", "type": "string", "minLength": 1 }, "location_id": { "description": "GoHighLevel Location ID to provision a GHL-connected subaccount from. Requires the key's workspace to have completed agency-level GHL OAuth. Idempotent per location. Provide EITHER name OR location_id, not both.", "type": "string", "minLength": 1 } }, "additionalProperties": false } } } } }, "get": { "summary": "List subaccounts", "operationId": "listSubaccounts", "tags": [ "Subaccounts" ], "description": "Requires scope `subaccounts:list`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubAccount" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "description": "Max rows to return (1–100, default 50).", "type": "integer", "minimum": 1, "maximum": 100 } } ] } }, "/v3/subaccounts/{id}": { "get": { "summary": "Get a subaccount", "operationId": "getSubaccount", "tags": [ "Subaccounts" ], "description": "Requires scope `subaccounts:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubAccount" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/subaccounts/{id}/users": { "post": { "summary": "Add a user to a subaccount", "operationId": "addSubaccountUser", "tags": [ "Subaccounts" ], "description": "Requires scope `subaccounts:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubAccountUser" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email — the login identity." }, "password": { "type": "string", "minLength": 8, "description": "Plain password, stored as a bcrypt hash (cost 12) — never persisted in plain text. If the email already belongs to an existing user, that user is linked to the subaccount and this password is IGNORED (an existing password is never changed by this endpoint)." }, "name": { "description": "Display name. Defaults to the email local-part.", "type": "string" }, "role": { "description": "Subaccount role. Defaults to MEMBER.", "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "VIEWER" ] } }, "required": [ "email", "password" ], "additionalProperties": false } } } } }, "get": { "summary": "List subaccount users", "operationId": "listSubaccountUsers", "tags": [ "Subaccounts" ], "description": "Requires scope `subaccounts:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubAccountMember" } }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/subaccounts/{id}/users/{userId}": { "patch": { "summary": "Update a subaccount user's role", "operationId": "updateSubaccountUser", "tags": [ "Subaccounts" ], "description": "Requires scope `subaccounts:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubAccountMemberRole" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER", "VIEWER" ], "description": "New subaccount role for the user." } }, "required": [ "role" ], "additionalProperties": false } } } } }, "delete": { "summary": "Remove a user from a subaccount", "operationId": "removeSubaccountUser", "tags": [ "Subaccounts" ], "description": "Requires scope `subaccounts:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/subaccounts/{id}/wallet": { "get": { "summary": "Get a subaccount's wallet balances", "operationId": "getSubaccountWallet", "tags": [ "Subaccounts" ], "description": "Requires scope `billing:read`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubAccountWallet" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ] } }, "/v3/subaccounts/{id}/wallet/credit": { "post": { "summary": "Credit a subaccount or workspace wallet", "operationId": "creditSubaccountWallet", "tags": [ "Subaccounts" ], "description": "Requires scope `billing:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubAccountWalletMutation" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_cents": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "Amount to move, in integer cents (1 – 100,000,000)." }, "target": { "description": "Which wallet plane to adjust. Defaults to 'workspace' — the plane the spend gate reads when running chat/voice.", "type": "string", "enum": [ "workspace", "subaccount" ] }, "description": { "description": "Audit note persisted on the ledger Transaction.", "type": "string", "maxLength": 500 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required caller-supplied dedup key. Repeating a credit/debit with the same key returns the original result without moving funds again — prevents double-charge on retry." } }, "required": [ "amount_cents", "idempotency_key" ], "additionalProperties": false } } } } } }, "/v3/subaccounts/{id}/wallet/debit": { "post": { "summary": "Debit a subaccount or workspace wallet", "operationId": "debitSubaccountWallet", "tags": [ "Subaccounts" ], "description": "Requires scope `billing:update`.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubAccountWalletMutation" }, "error": { "type": "null" }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "description": "Invalid request (validation_error / subaccount_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Insufficient scope or subaccount not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Resource not found (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit exceeded (rate_limited)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_cents": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "Amount to move, in integer cents (1 – 100,000,000)." }, "target": { "description": "Which wallet plane to adjust. Defaults to 'workspace' — the plane the spend gate reads when running chat/voice.", "type": "string", "enum": [ "workspace", "subaccount" ] }, "description": { "description": "Audit note persisted on the ledger Transaction.", "type": "string", "maxLength": 500 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required caller-supplied dedup key. Repeating a credit/debit with the same key returns the original result without moving funds again — prevents double-charge on retry." } }, "required": [ "amount_cents", "idempotency_key" ], "additionalProperties": false } } } } } } } }