{ "openapi": "3.1.0", "info": { "title": "Chatbase API v2", "version": "2.0.0", "description": "Chatbase API v2 - A robust, structured API for managing agents, conversations, and the helpdesk." }, "servers": [ { "url": "https://www.chatbase.co/api/v2", "description": "Chatbase API v2" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from your account settings" } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Field-level validation errors" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "UnixTimestamp": { "type": "number" }, "ListAgentsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null if no more pages" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "total": { "type": "number", "description": "Total number of items matching the query" } }, "required": [ "cursor", "hasMore", "total" ] } }, "required": [ "data", "pagination" ] }, "Agent": { "type": "object", "properties": { "id": { "type": "string", "description": "Agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "name": { "type": "string", "description": "Agent name", "example": "Support Bot" }, "instructions": { "type": "string", "description": "System prompt / instructions for the agent" }, "channelInstructions": { "type": [ "object", "null" ], "properties": { "chat_widget": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "help_page": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "center_stage": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "side_panel": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "slack": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "whatsapp": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "messenger": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "instagram": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "salesforce": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "zendesk": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "zendesk_messaging": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "api": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "android_sdk": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "ios_sdk": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] }, "search": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "chat": { "type": "string" }, "voice": { "type": "string" } } } ] } }, "description": "Per-channel instruction overrides" }, "model": { "type": "string", "enum": [ "gpt-4o-mini", "gpt-oss-120b", "gpt-oss-20b", "gpt-5.1", "gpt-5.2", "gpt-5.5", "gpt-5.6-terra", "gpt-6.1-sol", "gpt-6.1-terra", "gpt-6-luna", "claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5", "gemini-2.5-pro", "gemini-3-flash", "gemini-3.1-flash-lite", "gemini-3.1-pro", "gemini-3.5-flash-lite", "gemini-3.6-flash", "gemini-3.8-flash", "grok-4.7", "DeepSeek-V3.1", "DeepSeek-R1", "DeepSeek-V4-Flash", "DeepSeek-V4.1-Flash", "kimi-k2.6", "mistral-medium-3.5", "mistral-small-2603", "glm-5.2", "glm-5.3-flash", "auto" ], "description": "AI model used by the agent. Can be a deprecated model for agents that were configured before it was retired.", "example": "gpt-5.6-terra" }, "autoRetrain": { "type": "boolean", "description": "Whether the agent automatically retrains every 7 days" }, "temp": { "type": "number", "minimum": 0, "maximum": 1, "description": "Model temperature (0–1)", "example": 0 }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "Whether the agent is publicly accessible or private" }, "allowedDomains": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Domains allowed to embed this agent" }, "suggestedMessages": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "single" ] }, "order": { "type": "number" }, "icon": { "type": [ "string", "null" ] } }, "required": [ "text", "type", "order" ] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "nested" ] }, "order": { "type": "number" }, "icon": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "order": { "type": "number" }, "icon": { "type": [ "string", "null" ] } }, "required": [ "text", "order" ] }, "minItems": 1, "maxItems": 20 } }, "required": [ "name", "type", "order", "items" ] } ] }, "description": "Suggested quick-reply messages shown to users" }, "initialMessages": { "type": "array", "items": { "type": "string" }, "description": "Initial messages shown when a conversation starts" }, "creditLimit": { "type": [ "integer", "null" ], "description": "Per-agent credit limit (null = no limit)" }, "creditsUsed": { "type": "integer", "description": "Credits consumed by this agent since the start of the current calendar month (UTC). Resets to 0 on the 1st of each month.", "example": 1284 }, "notificationsSettings": { "type": [ "object", "null" ], "properties": { "dailyLeadsCollected": { "type": "object", "properties": { "active": { "type": "boolean" }, "emails": { "type": "array", "items": { "type": "string", "pattern": "^\\w+([+.-]?\\w+)*@\\w+([.-]?\\w+)*(\\.\\w{2,})+$" }, "maxItems": 10 } }, "required": [ "active", "emails" ] }, "dailyConversations": { "type": "object", "properties": { "active": { "type": "boolean" }, "emails": { "type": "array", "items": { "type": "string", "pattern": "^\\w+([+.-]?\\w+)*@\\w+([.-]?\\w+)*(\\.\\w{2,})+$" }, "maxItems": 10 } }, "required": [ "active", "emails" ] } }, "required": [ "dailyLeadsCollected", "dailyConversations" ], "description": "Email notification settings including recipient addresses" }, "ipRateLimits": { "$ref": "#/components/schemas/AgentIpRateLimits" }, "spamSettings": { "$ref": "#/components/schemas/AgentSpamSettings" }, "blockedCountries": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country codes blocked from accessing this agent. Visitors from these countries will not see the chatbot.", "example": [ "RU", "KP" ] }, "voiceSettings": { "type": [ "object", "null" ], "properties": { "voice": { "type": "object", "properties": { "voiceName": { "type": "string" }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.2 }, "stability": { "type": "number", "minimum": 0, "maximum": 1 }, "similarity": { "type": "number", "minimum": 0, "maximum": 1 }, "instructions": { "type": "string", "maxLength": 500 } }, "required": [ "speed", "stability", "similarity" ] }, "transcriber": { "type": "object", "properties": { "model": { "type": "string" }, "language": { "type": "string" }, "minSilenceDuration": { "type": "number", "minimum": 0.1, "maximum": 3 }, "activationThreshold": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "model", "language", "minSilenceDuration", "activationThreshold" ] }, "recordings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "retentionDays": { "type": "integer", "minimum": 0 } }, "required": [ "enabled", "retentionDays" ] }, "maxConcurrentSessions": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "maxCallDurationSeconds": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "maxDailyCallsPerUser": { "type": [ "integer", "null" ], "exclusiveMinimum": 0 }, "model": { "type": "string", "enum": [ "gpt-4o-mini", "gpt-oss-120b", "gpt-oss-20b", "gpt-5.1", "gpt-5.2", "gpt-5.5", "gpt-5.6-terra", "gpt-6.1-sol", "gpt-6.1-terra", "gpt-6-luna", "claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5", "gemini-2.5-pro", "gemini-3-flash", "gemini-3.1-flash-lite", "gemini-3.1-pro", "gemini-3.5-flash-lite", "gemini-3.6-flash", "gemini-3.8-flash", "grok-4.7", "DeepSeek-V3.1", "DeepSeek-R1", "DeepSeek-V4-Flash", "DeepSeek-V4.1-Flash", "kimi-k2.6", "mistral-medium-3.5", "mistral-small-2603", "glm-5.2", "glm-5.3-flash", "auto" ] }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "allowInterruptions": { "type": "boolean" }, "allowTextInput": { "type": "boolean" }, "endConversationAfterSilenceSeconds": { "type": [ "integer", "null" ], "minimum": 10 }, "initialMessage": { "type": "string", "maxLength": 500 }, "errorMessage": { "type": "string", "maxLength": 500 }, "visualization": { "type": "object", "properties": { "style": { "type": "string", "enum": [ "basic", "orb" ] }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "contrast": { "type": "number", "minimum": 0.5, "maximum": 3 }, "flow": { "type": "number", "minimum": 0, "maximum": 3 }, "swirl": { "type": "number", "minimum": 0, "maximum": 3 } }, "required": [ "style", "color", "contrast", "flow", "swirl" ], "description": "What users see during a voice conversation: a basic ring or a customizable orb." }, "mode": { "type": "string", "enum": [ "live", "classic" ], "description": "`live`: the agent listens and speaks with one realtime model, replying almost instantly. `classic`: a separate transcriber and voice, with more languages and custom voices." }, "liveVoice": { "type": "string", "enum": [ "marin", "beacon", "bossa", "brise", "cinder", "delta", "flitz", "gleam", "harema", "juni", "meridian", "nira", "noeul", "nuri", "quartz", "ripple", "shida", "sillage", "stone", "tempo", "vesper", "willow" ], "description": "Voice used when `mode` is `live`." }, "liveInstructions": { "type": "string", "maxLength": 500, "description": "How the voice sounds when `mode` is `live`: tone, pace, formality and emotion." } }, "required": [ "visualization", "mode" ], "description": "Voice mode settings" }, "styles": { "$ref": "#/components/schemas/AgentStyles" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp", "example": "2024-01-15T10:30:00.000Z" }, "lastMessageAt": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the last received message" }, "lastTrainedAt": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the last completed training" }, "status": { "type": "string", "enum": [ "untrained", "training", "failed", "trained" ], "description": "Training state derived from the agent's sources. `untrained`: no live sources. `training`: at least one source is still being processed. `failed`: a source failed to train (the others are live). `trained`: every source is live.", "example": "trained" }, "size": { "type": "number", "description": "Total size of training data in bytes" } }, "required": [ "id", "name", "instructions", "channelInstructions", "model", "autoRetrain", "temp", "visibility", "allowedDomains", "suggestedMessages", "initialMessages", "creditLimit", "creditsUsed", "notificationsSettings", "ipRateLimits", "spamSettings", "blockedCountries", "voiceSettings", "styles", "createdAt", "lastMessageAt", "lastTrainedAt", "status", "size" ] }, "AgentIpRateLimits": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum messages per timeframe (1–200)", "example": 20 }, "timeframe": { "type": "integer", "minimum": 1, "maximum": 3600, "description": "Timeframe in seconds for the rate limit (1–3600)", "example": 240 }, "message": { "type": "string", "description": "Message shown when rate limit is exceeded", "example": "Too many messages in a row" } }, "required": [ "limit", "timeframe", "message" ] }, "AgentSpamSettings": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean", "description": "Whether spam detection is enabled" }, "prompt": { "type": "string", "description": "Custom prompt describing what counts as spam for this agent (max 2000 chars)" } }, "required": [ "enabled", "prompt" ], "description": "Spam detection settings. When enabled, conversations are checked for spam and automatically paused." }, "AgentStyles": { "type": [ "object", "null" ], "properties": { "chat": { "type": [ "object", "null" ], "properties": { "theme": { "type": "string", "enum": [ "light", "dark" ], "default": "light" }, "buttonColor": { "anyOf": [ { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i" }, { "type": "string", "enum": [ "transparent" ] } ] }, "headerColor": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i" }, "userMessageColor": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i" }, "displayName": { "type": [ "string", "null" ] }, "autoOpenChatWindowAfter": { "type": [ "number", "null" ] }, "mobile": { "type": [ "object", "null" ], "properties": { "initialMessages": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean" }, "value": { "type": "array", "items": { "type": "string" } } }, "required": [ "enabled", "value" ] }, "autoOpenChatWindowAfter": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean" }, "value": { "type": "number" } }, "required": [ "enabled", "value" ] }, "showAutoOpen": { "type": [ "boolean", "null" ] } } }, "alignChatButton": { "type": [ "string", "null" ], "enum": [ "left", "right", null ] }, "messagePlaceholder": { "type": [ "string", "null" ] }, "footer": { "type": [ "string", "null" ] }, "showFeedback": { "type": [ "boolean", "null" ] }, "showCopyButton": { "type": [ "boolean", "null" ] }, "dismissableNotice": { "type": [ "string", "null" ] }, "showDictation": { "type": [ "boolean", "null" ] }, "showAttachments": { "type": [ "boolean", "null" ] }, "showVoiceMode": { "type": [ "boolean", "null" ] } }, "description": "Chat widget styles" }, "centerStage": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean", "default": false }, "theme": { "type": "string", "enum": [ "light", "dark" ], "default": "light" }, "displayName": { "type": [ "string", "null" ] }, "welcomeMessage": { "type": [ "string", "null" ] }, "messagePlaceholder": { "type": [ "string", "null" ] }, "footer": { "type": [ "string", "null" ] }, "dismissableNotice": { "type": [ "string", "null" ] }, "suggestedMessages": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "single" ] }, "order": { "type": "number" }, "icon": { "type": [ "string", "null" ] } }, "required": [ "text", "type", "order" ] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "nested" ] }, "order": { "type": "number" }, "icon": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "order": { "type": "number" }, "icon": { "type": [ "string", "null" ] } }, "required": [ "text", "order" ] }, "minItems": 1, "maxItems": 20 } }, "required": [ "name", "type", "order", "items" ] } ] } }, "showChatBubble": { "type": "boolean", "default": true }, "showAttachments": { "type": "boolean", "default": false }, "showDictation": { "type": "boolean", "default": true }, "showVoiceMode": { "type": "boolean", "default": false }, "showCopyButton": { "type": "boolean", "default": false }, "showFeedback": { "type": "boolean", "default": true }, "showDataSource": { "type": "boolean", "default": true }, "headerColor": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i" }, "userMessageColor": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i" }, "tintedGrayscale": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "hue": { "type": "number", "minimum": 0, "maximum": 360, "default": 0 }, "tint": { "type": "number", "minimum": 0, "maximum": 9 }, "shade": { "type": "number", "minimum": -4, "maximum": 4 } } }, "accentColorEnabled": { "type": "boolean" }, "accentSyncWithIcon": { "type": "boolean" }, "typography": { "type": "object", "properties": { "fontFamily": { "type": "string", "pattern": "^[a-zA-Z0-9 ,'\"_-]+$", "default": "Inter" }, "fontSize": { "type": "string", "pattern": "^\\d+(\\.\\d+)?(px|rem|em)$", "default": "14px" } } }, "closeOnOutsideClick": { "type": "boolean", "default": true } }, "description": "Center stage widget styles" } }, "required": [ "chat", "centerStage" ] }, "AgentCreatedResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "pendingSteps": { "type": "array", "items": { "type": "string", "enum": [ "ADD_SOURCE", "TRAIN_AGENT" ] }, "description": "Steps that failed after the agent was created, absent when everything succeeded. ADD_SOURCE — the provided URL could not be added as a source; add sources manually via the Sources API. TRAIN_AGENT — training could not be started; trigger it manually via POST /agents/{agentId}/train." } }, "required": [ "id" ] }, "CreateAgentBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Agent name", "example": "Support Bot" }, "url": { "type": "string", "format": "uri", "description": "Homepage URL of the product. The agent is pre-configured to answer questions about this website.", "example": "https://example.com" }, "instructions": { "type": "string", "maxLength": 30000, "description": "System prompt / instructions for the agent (max 30,000 characters)" }, "model": { "type": "string", "enum": [ "gpt-oss-120b", "gpt-oss-20b", "gpt-5.2", "gpt-5.5", "gpt-5.6-terra", "gpt-6.1-sol", "gpt-6.1-terra", "gpt-6-luna", "claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5", "gemini-2.5-pro", "gemini-3-flash", "gemini-3.1-flash-lite", "gemini-3.1-pro", "gemini-3.5-flash-lite", "gemini-3.6-flash", "gemini-3.8-flash", "grok-4.7", "DeepSeek-V3.1", "DeepSeek-R1", "DeepSeek-V4-Flash", "DeepSeek-V4.1-Flash", "kimi-k2.6", "mistral-medium-3.5", "mistral-small-2603", "glm-5.2", "glm-5.3-flash", "auto" ], "description": "AI model to use", "example": "gpt-5.6-terra" }, "temp": { "type": "number", "minimum": 0, "maximum": 1, "description": "Model temperature (0–1)", "example": 0 }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "Agent visibility (default: private)" } }, "required": [ "name" ] }, "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] } }, "required": [ "success" ] }, "UpdateAgentBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Agent name" }, "instructions": { "type": "string", "maxLength": 30000, "description": "System prompt (max 30,000 characters)" }, "channelInstructions": { "type": [ "object", "null" ], "properties": { "chat_widget": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "help_page": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "center_stage": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "side_panel": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "slack": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "whatsapp": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "messenger": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "instagram": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "salesforce": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "zendesk": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "zendesk_messaging": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "api": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "email": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "android_sdk": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "ios_sdk": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] }, "search": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "object", "properties": { "chat": { "type": "string", "maxLength": 30000 }, "voice": { "type": "string", "maxLength": 30000 } } } ] } }, "description": "Per-channel instruction overrides (max 30,000 characters each)" }, "model": { "type": "string", "enum": [ "gpt-oss-120b", "gpt-oss-20b", "gpt-5.2", "gpt-5.5", "gpt-5.6-terra", "gpt-6.1-sol", "gpt-6.1-terra", "gpt-6-luna", "claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5", "gemini-2.5-pro", "gemini-3-flash", "gemini-3.1-flash-lite", "gemini-3.1-pro", "gemini-3.5-flash-lite", "gemini-3.6-flash", "gemini-3.8-flash", "grok-4.7", "DeepSeek-V3.1", "DeepSeek-R1", "DeepSeek-V4-Flash", "DeepSeek-V4.1-Flash", "kimi-k2.6", "mistral-medium-3.5", "mistral-small-2603", "glm-5.2", "glm-5.3-flash", "auto" ], "description": "AI model", "example": "gpt-5.6-terra" }, "temp": { "type": "number", "minimum": 0, "maximum": 1, "description": "Temperature (0–1)" }, "visibility": { "type": "string", "enum": [ "public", "private" ], "description": "Visibility" }, "allowedDomains": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Allowed embed domains" }, "suggestedMessages": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "single" ] }, "order": { "type": "number" }, "icon": { "type": [ "string", "null" ] } }, "required": [ "text", "type", "order" ] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "nested" ] }, "order": { "type": "number" }, "icon": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "order": { "type": "number" }, "icon": { "type": [ "string", "null" ] } }, "required": [ "text", "order" ] }, "minItems": 1, "maxItems": 20 } }, "required": [ "name", "type", "order", "items" ] } ] }, "description": "Suggested messages" }, "initialMessages": { "type": "array", "items": { "type": "string" }, "description": "Initial messages" }, "creditLimit": { "type": [ "integer", "null" ], "description": "Per-agent credit limit (null = no limit)" }, "notificationsSettings": { "type": [ "object", "null" ], "properties": { "dailyLeadsCollected": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether this notification type is enabled" }, "emails": { "type": "array", "items": { "type": "string", "pattern": "^\\w+([+.-]?\\w+)*@\\w+([.-]?\\w+)*(\\.\\w{2,})+$", "example": "alerts@company.com" }, "maxItems": 10, "description": "Recipient email addresses (max 10)" } }, "required": [ "active", "emails" ], "description": "Daily summary of new leads collected by this agent" }, "dailyConversations": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether this notification type is enabled" }, "emails": { "type": "array", "items": { "type": "string", "pattern": "^\\w+([+.-]?\\w+)*@\\w+([.-]?\\w+)*(\\.\\w{2,})+$", "example": "alerts@company.com" }, "maxItems": 10, "description": "Recipient email addresses (max 10)" } }, "required": [ "active", "emails" ], "description": "Daily summary of conversation volume for this agent" } }, "description": "Email notification settings (null = disable all notifications)" }, "ipRateLimits": { "type": [ "object", "null" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum messages per timeframe (1–200)", "example": 20 }, "timeframe": { "type": "integer", "minimum": 1, "maximum": 3600, "description": "Timeframe in seconds for the rate limit (1–3600)", "example": 240 }, "message": { "type": "string", "description": "Message shown when rate limit is exceeded", "example": "Too many messages in a row" } }, "description": "IP-based rate limit settings (partial update; null = reset to defaults)" }, "spamSettings": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean", "description": "Whether spam detection is enabled" }, "prompt": { "type": "string", "maxLength": 2000, "description": "Custom prompt describing what counts as spam for this agent (max 2000 chars)" } }, "required": [ "enabled", "prompt" ], "description": "Spam detection settings (null = disable spam detection)" }, "voiceSettings": { "type": [ "object", "null" ], "properties": { "mode": { "type": "string", "enum": [ "live", "classic" ], "description": "`live`: the agent listens and speaks with one realtime model, replying almost instantly. `classic`: a separate transcriber and voice, with more languages and custom voices. `voice` and `transcriber` apply to `classic` only.", "example": "live" }, "liveVoice": { "type": "string", "enum": [ "marin", "beacon", "bossa", "brise", "cinder", "delta", "flitz", "gleam", "harema", "juni", "meridian", "nira", "noeul", "nuri", "quartz", "ripple", "shida", "sillage", "stone", "tempo", "vesper", "willow" ], "description": "Voice used when `mode` is `live`.", "example": "marin" }, "liveInstructions": { "type": "string", "maxLength": 500, "description": "How the voice sounds when `mode` is `live`: tone, pace, formality and emotion (max 500 chars). Write it in the language the agent speaks. An empty string clears it.", "example": "Speak warmly and naturally, at an unhurried pace. Sound friendly but professional." }, "voice": { "type": "object", "properties": { "voiceName": { "type": "string", "enum": [ "Sarah", "Laura", "Alice", "Matilda", "Jessica", "Lily", "Bella", "Roger", "George", "Charlie", "Adam", "Daniel", "Brian", "Eric", "Chris", "Liam", "Harry", "Will", "Bill", "Callum", "Masry", "Hanafi", "Alberto Rodríguez", "Jhenny", "Anna", "Peter", "Marc Aurèle", "Marie Line", "Yasmin Alves", "Lax", "Skylar", "Corey", "Jacqueline", "Blake", "Pedro", "Marta", "Alloy", "Ash", "Ballad", "Coral", "Echo", "Fable", "Nova", "Onyx", "Sage", "Shimmer", "Nouran", "Nermin", "Othman", "Layla", "Nada", "Mariam", "Samir", "Eman", "Haneen", "Fahd", "Jasem", "Marwa", "Razan", "Yehya", "Hamdan", "Zephyr", "Puck", "Charon", "Kore", "Fenrir", "Leda", "Orus", "Aoede", "Enceladus", "Sulafat", "Mina", "Nina", "Ruby", "Mason", "Rohan" ], "example": "Corey", "description": "Name of the voice for this agent." }, "speed": { "type": "number", "minimum": 0.7, "maximum": 1.2, "description": "Speech rate multiplier (0.7–1.2). Only supported on select voices; ignored for others.", "example": 1 }, "stability": { "type": "number", "minimum": 0, "maximum": 1, "description": "Voice consistency (0–1). Higher values produce more consistent delivery. Only supported on select voices; ignored for others.", "example": 0.5 }, "similarity": { "type": "number", "minimum": 0, "maximum": 1, "description": "How closely the output matches the reference voice sample (0–1). Only supported on select voices; ignored for others.", "example": 0.75 }, "instructions": { "type": "string", "maxLength": 500, "description": "Natural-language delivery instructions for the voice (max 500 chars). Only supported on select voices; ignored for others.", "example": "Speak slowly and clearly." } }, "required": [ "voiceName" ], "description": "Text-to-speech voice configuration" }, "transcriber": { "type": "object", "properties": { "model": { "type": "string", "enum": [ "elevenlabs/scribe_v2_realtime", "cartesia/ink-2", "cartesia/ink-whisper", "deepgram/nova-3", "deepgram/nova-2", "deepgram/flux-general-multi", "soniox/stt-rt-v5", "soniox/stt-rt-v4", "google/gemini-3.5-transcribe-live", "hamsa/hamsa-ar" ], "example": "soniox/stt-rt-v5", "description": "Speech-to-text model to use for this agent." }, "language": { "type": "string", "description": "BCP-47 language code for speech recognition (e.g. \"en\", \"fr\", \"ar\"). Use \"multi\" for automatic detection. Valid codes depend on the selected model.", "example": "multi" }, "minSilenceDuration": { "type": "number", "minimum": 0.1, "maximum": 3, "description": "Seconds of continuous silence that signals the user has finished speaking (0.1–3.0). Lower values make the agent respond faster but may cut off slow speakers.", "example": 0.75 }, "activationThreshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "Voice activity detection sensitivity (0–1). Lower values detect quieter speech but may pick up background noise. Higher values require clearer speech to activate.", "example": 0.5 } }, "required": [ "model", "language", "minSilenceDuration", "activationThreshold" ], "description": "Speech-to-text (voice input) configuration" }, "recordings": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether voice calls are recorded and stored" }, "retentionDays": { "type": "integer", "minimum": 0, "description": "How many days recordings are kept before automatic deletion. 0 disables storage even when enabled is true.", "example": 30 } }, "required": [ "enabled", "retentionDays" ], "description": "Call recording and retention settings" }, "maxConcurrentSessions": { "type": [ "integer", "null" ], "exclusiveMinimum": 0, "description": "Maximum simultaneous active voice calls for this agent. null = no limit.", "example": 5 }, "maxCallDurationSeconds": { "type": [ "integer", "null" ], "exclusiveMinimum": 0, "description": "Maximum length of a single call in seconds. The call ends automatically when reached. null = no limit.", "example": 900 }, "maxDailyCallsPerUser": { "type": [ "integer", "null" ], "exclusiveMinimum": 0, "description": "Maximum voice calls a single user can start per calendar day. null = no limit.", "example": 10 }, "model": { "type": "string", "enum": [ "gpt-oss-120b", "gpt-oss-20b", "gpt-5.2", "gpt-5.5", "gpt-5.6-terra", "gpt-6.1-sol", "gpt-6.1-terra", "gpt-6-luna", "claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5", "gemini-2.5-pro", "gemini-3-flash", "gemini-3.1-flash-lite", "gemini-3.1-pro", "gemini-3.5-flash-lite", "gemini-3.6-flash", "gemini-3.8-flash", "grok-4.7", "DeepSeek-V3.1", "DeepSeek-R1", "DeepSeek-V4-Flash", "DeepSeek-V4.1-Flash", "kimi-k2.6", "mistral-medium-3.5", "mistral-small-2603", "glm-5.2", "glm-5.3-flash", "auto" ], "description": "AI model used to generate responses during a voice call. Can be set independently from the chat model — faster, cheaper models are common here.", "example": "gpt-6-luna" }, "temperature": { "type": "number", "minimum": 0, "maximum": 1, "description": "Randomness of voice responses (0–1). 0 = deterministic and focused, 1 = more varied and creative.", "example": 0 }, "allowInterruptions": { "type": "boolean", "description": "When true the user can speak while the agent is talking and the agent will stop and listen. When false the agent finishes its turn before processing new speech." }, "allowTextInput": { "type": "boolean", "description": "When true users can also type messages during a voice session instead of only speaking." }, "endConversationAfterSilenceSeconds": { "type": [ "integer", "null" ], "minimum": 10, "description": "Seconds of inactivity before the session ends automatically. Minimum 10 seconds. null = session never auto-ends.", "example": 300 }, "initialMessage": { "type": "string", "maxLength": 500, "description": "Message the agent speaks immediately when a voice session starts, before the user says anything. Leave empty to wait for the user to speak first (max 500 chars)." }, "errorMessage": { "type": "string", "maxLength": 500, "description": "Fallback message spoken to the user when the agent encounters an unrecoverable error during a call (max 500 chars)." }, "visualization": { "type": "object", "properties": { "style": { "type": "string", "enum": [ "basic", "orb" ], "description": "basic shows a minimal ring that follows the widget theme. orb shows a fluid sphere tuned by the fields below." }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Orb base color as a 6-digit hex.", "example": "#C1D4E6" }, "contrast": { "type": "number", "minimum": 0.5, "maximum": 3, "description": "Orb contrast (0.5–3).", "example": 1 }, "flow": { "type": "number", "minimum": 0, "maximum": 3, "description": "Orb animation speed (0–3).", "example": 2.5 }, "swirl": { "type": "number", "minimum": 0, "maximum": 3, "description": "Orb swirl strength (0–3).", "example": 1 } }, "description": "Voice visualization shown during voice conversations. Omitted fields keep their current values." } }, "description": "Voice mode configuration (null = disable voice mode)" }, "blockedCountries": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "maxItems": 300, "description": "ISO 3166-1 alpha-2 country codes to block (null = remove all blocking)", "example": [ "RU", "KP" ] } } }, "UpdateAgentStylesBody": { "type": "object", "properties": { "styles": { "$ref": "#/components/schemas/UpdateAgentStylesInput" } }, "required": [ "styles" ] }, "UpdateAgentStylesInput": { "type": "object", "properties": { "chat": { "type": "object", "properties": { "theme": { "type": "string", "enum": [ "light", "dark" ], "description": "Widget color theme", "example": "light" }, "headerColor": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i", "example": "#1A2B3C", "description": "Chat header background color (hex, e.g. #1A2B3C)" }, "userMessageColor": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i", "example": "#1A2B3C", "description": "User message bubble background color (hex)" }, "buttonColor": { "anyOf": [ { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i", "example": "#1A2B3C" }, { "type": "string", "enum": [ "transparent" ] } ], "description": "Chat launcher button and primary accent color. Pass a hex code or \"transparent\"", "example": "#1A2B3C" }, "displayName": { "type": [ "string", "null" ], "maxLength": 100, "description": "Name displayed in the chat header. Defaults to the agent name (max 100 chars)" }, "autoOpenChatWindowAfter": { "type": [ "number", "null" ], "description": "Seconds after page load before the chat window opens automatically. null = disabled", "example": 5 }, "mobile": { "type": "object", "properties": { "initialMessages": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean" }, "value": { "type": "array", "items": { "type": "string" } } }, "required": [ "enabled", "value" ] }, "autoOpenChatWindowAfter": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean" }, "value": { "type": "number" } }, "required": [ "enabled", "value" ] }, "showAutoOpen": { "type": [ "boolean", "null" ] } }, "description": "Mobile-specific overrides for initial messages and auto-open timing" }, "alignChatButton": { "type": "string", "enum": [ "left", "right" ], "description": "Corner the launcher button is anchored to", "example": "right" }, "messagePlaceholder": { "type": [ "string", "null" ], "maxLength": 200, "description": "Placeholder text shown inside the message input field (max 200 chars)" }, "footer": { "type": [ "string", "null" ], "maxLength": 500, "description": "Small text shown below the input bar, e.g. branding or legal notice (max 500 chars)" }, "showFeedback": { "type": "boolean", "description": "Show thumbs-up / thumbs-down buttons on agent messages" }, "showCopyButton": { "type": "boolean", "description": "Show a copy-to-clipboard button on agent messages" }, "dismissableNotice": { "type": [ "string", "null" ], "maxLength": 500, "description": "Text shown in a dismissable banner above the chat. Empty string = hidden (max 500 chars)" }, "showDictation": { "type": "boolean", "description": "Show a microphone button for speech-to-text input" }, "showAttachments": { "type": "boolean", "description": "Allow users to attach files to their messages" }, "showVoiceMode": { "type": "boolean", "description": "Show the voice-conversation mode button in the chat" } }, "description": "Chat widget styles" }, "centerStage": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Enable or disable the Center Stage widget entirely" }, "displayName": { "type": [ "string", "null" ], "maxLength": 100, "description": "Name shown in the widget header. Defaults to the agent name (max 100 chars)" }, "welcomeMessage": { "type": [ "string", "null" ], "maxLength": 500, "description": "Greeting text shown above the message input when the conversation is empty (max 500 chars)" }, "messagePlaceholder": { "type": [ "string", "null" ], "maxLength": 200, "description": "Placeholder text inside the message input field (max 200 chars)" }, "dismissableNotice": { "type": [ "string", "null" ], "maxLength": 500, "description": "Text shown in a dismissable banner inside the widget. Empty string = hidden (max 500 chars)" }, "footer": { "type": [ "string", "null" ], "maxLength": 500, "description": "Small text below the input bar, e.g. branding or legal notice (max 500 chars)" }, "suggestedMessages": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "single" ] }, "order": { "type": "number" }, "icon": { "type": [ "string", "null" ] } }, "required": [ "text", "type", "order" ] }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "nested" ] }, "order": { "type": "number" }, "icon": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "order": { "type": "number" }, "icon": { "type": [ "string", "null" ] } }, "required": [ "text", "order" ] }, "minItems": 1, "maxItems": 20 } }, "required": [ "name", "type", "order", "items" ] } ] }, "description": "Quick-reply buttons shown to the user at the start of the conversation" }, "showChatBubble": { "type": "boolean", "description": "Wrap agent messages in a chat bubble style" }, "showAttachments": { "type": "boolean", "description": "Allow users to attach files to their messages" }, "showDictation": { "type": "boolean", "description": "Show a microphone button for speech-to-text input" }, "showVoiceMode": { "type": "boolean", "description": "Show the voice-conversation mode button" }, "showCopyButton": { "type": "boolean", "description": "Show a copy-to-clipboard button on agent messages" }, "showFeedback": { "type": "boolean", "description": "Show thumbs-up / thumbs-down feedback buttons on agent messages" }, "showDataSource": { "type": "boolean", "description": "Show the source citation below agent messages" }, "theme": { "type": "string", "enum": [ "light", "dark" ], "description": "Widget color theme", "example": "light" }, "buttonColor": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i", "example": "#1A2B3C", "description": "Primary accent / send-button color (hex)" }, "headerColor": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i", "example": "#1A2B3C", "description": "Header bar background color (hex)" }, "userMessageColor": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i", "example": "#1A2B3C", "description": "User message bubble background color (hex)" }, "tintedGrayscale": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether tinted grayscale is active" }, "hue": { "type": "number", "minimum": 0, "maximum": 360, "description": "Base hue for the grayscale tint (0–360°)", "example": 220 }, "tint": { "type": "number", "minimum": 0, "maximum": 10, "description": "Amount of hue mixed into lighter tones (0–10)", "example": 3 }, "shade": { "type": "number", "minimum": 0, "maximum": 10, "description": "Amount of hue mixed into darker tones (0–10)", "example": 3 } }, "required": [ "enabled", "hue", "tint", "shade" ], "description": "Tinted grayscale palette. When enabled the widget uses shades of a single hue instead of neutral gray" }, "accentColor": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the custom accent color is active" }, "color": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i", "example": "#1A2B3C", "description": "Accent color applied to interactive elements (hex)" } }, "required": [ "enabled", "color" ], "description": "Custom accent color override for interactive elements" }, "customSurfaceColors": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether custom surface colors are active" }, "background": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i", "example": "#1A2B3C", "description": "Widget background color (hex)" }, "foreground": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i", "example": "#1A2B3C", "description": "Primary text color on the background (hex)" } }, "required": [ "enabled", "background", "foreground" ], "description": "Override the widget background and foreground colors" }, "typography": { "type": "object", "properties": { "fontFamily": { "type": "string", "enum": [ "Inter", "System", "Arial", "Helvetica", "Georgia", "Geist" ], "description": "Widget font family", "example": "Inter" }, "fontSize": { "type": "string", "enum": [ "12px", "14px", "16px", "18px", "20px" ], "description": "Widget base font size", "example": "16px" } }, "required": [ "fontFamily", "fontSize" ], "description": "Widget font family and size" }, "width": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "Widget width preset (small ≈ 360 px, medium ≈ 420 px, large ≈ 520 px)", "example": "medium" }, "closeOnOutsideClick": { "type": "boolean", "description": "Close the widget when the user clicks outside of it" }, "notificationIndicator": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the notification badge is shown" }, "number": { "type": "integer", "minimum": 0, "maximum": 99, "description": "Number displayed in the badge (0–99)", "example": 3 } }, "required": [ "enabled", "number" ], "description": "Numeric badge on the launcher to draw attention before the user opens the widget" }, "notificationMessage": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the notification message bubble is shown" }, "text": { "type": "string", "maxLength": 200, "description": "Message text displayed in the bubble (max 200 chars)" } }, "required": [ "enabled", "text" ], "description": "Floating message bubble next to the launcher shown before the user opens the widget" } }, "description": "Center stage widget styles" } } }, "UpdateAgentAutoRetrainBody": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "true = retrain every 7 days, false = never" } }, "required": [ "enabled" ] }, "DeprecatedEndpointResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "deprecated": { "type": "boolean", "enum": [ true ] }, "message": { "type": "string", "example": "Deprecated: this endpoint does nothing. Sources train as soon as they are created, updated or deleted, so changes take effect immediately. Poll GET /agents/{agentId}/sources/{sourceId} for a source status." } }, "required": [ "success", "deprecated", "message" ] }, "StreamFinishMetadata": { "type": "object", "properties": { "messageId": { "type": "string", "description": "Unique ID of the assistant message" }, "userMessageId": { "type": "string", "description": "The ID of the user message that triggered this response. For continuation responses, this is the last user message in the conversation." }, "conversationId": { "type": "string", "description": "The conversation ID. Use this for follow-up messages." }, "userId": { "type": [ "string", "null" ], "description": "The user ID associated with this conversation, or null if none" }, "usage": { "type": "object", "properties": { "credits": { "type": "number", "description": "Credits consumed by this request", "example": 2 } }, "required": [ "credits" ], "description": "Usage information for this request" } }, "required": [ "messageId", "userMessageId", "conversationId", "userId", "usage" ], "description": "Streaming response using the AI SDK UIMessage Stream protocol.\n\nEach SSE event has an `event:` field with the type and a `data:` field with JSON content.\n\n**AI SDK events:**\n- `message-start` — `{ type, messageId }` — Start of a new message\n- `text-start` — `{ type, id }` — Start of a text block\n- `text-delta` — `{ type, id, delta }` — Incremental text chunk\n- `text-end` — `{ type, id }` — End of a text block\n- `tool-input-start` — `{ type, toolCallId, toolName }` — Start of tool call input\n- `tool-input-delta` — `{ type, toolCallId, inputTextDelta }` — Incremental tool input\n- `tool-input-available` — `{ type, toolCallId, toolName, input }` — Complete tool input\n- `tool-output-available` — `{ type, toolCallId, output }` — Tool execution result\n- `start-step` — `{ type }` — Start of a processing step\n- `finish-step` — `{ type }` — End of a processing step\n- `finish` — `{ type }` — Stream complete\n- `error` — `{ type, errorText }` — Error occurred\n\n**Chatbase metadata (emitted as `message-metadata` on the finish event):**\nThe schema below describes the custom metadata attached to the `finish` event. Use `conversationId` for follow-up messages.\n\nStream terminates with `data: [DONE]`." }, "ChatResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique message ID", "example": "msg_abc123" }, "role": { "type": "string", "enum": [ "assistant" ], "description": "The message role (always \"assistant\" for responses)" }, "parts": { "$ref": "#/components/schemas/MessageParts" }, "metadata": { "type": "object", "properties": { "userMessageId": { "type": "string", "description": "The ID of the user message that triggered this response. For continuation responses, this is the last user message in the conversation." }, "conversationId": { "type": "string", "description": "The conversation ID. Use this for follow-up messages to continue the conversation." }, "userId": { "type": [ "string", "null" ], "description": "The user ID associated with this conversation, or null if none" }, "finishReason": { "type": "string", "enum": [ "stop", "error", "tool-calls" ], "description": "Why the model stopped generating. \"stop\" means normal completion, \"error\" means an error occurred, \"tool-calls\" means the model invoked a client-side action — submit the tool result and continue the conversation." }, "usage": { "type": "object", "properties": { "credits": { "type": "number", "description": "Credits consumed by this request", "example": 2 } }, "required": [ "credits" ], "description": "Usage information for this request" } }, "required": [ "userMessageId", "conversationId", "userId", "finishReason", "usage" ], "description": "Response metadata including conversation tracking" } }, "required": [ "id", "role", "parts", "metadata" ] }, "MessageParts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool-call" ] }, "toolCallId": { "type": "string" }, "toolName": { "type": "string" }, "input": {} }, "required": [ "type", "toolCallId", "toolName" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool-result" ] }, "toolCallId": { "type": "string" }, "toolName": { "type": "string" }, "output": {} }, "required": [ "type", "toolCallId", "toolName" ] } ] }, "description": "Message content parts. Can include text, tool calls, and tool results. Use this for full detail including tool interactions." }, "ChatRequest": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "description": "The user message to send to the agent. Omit to continue the conversation after submitting a tool result.", "example": "Hello, how can you help me?" }, "conversationId": { "type": "string", "description": "Optional conversation ID to continue an existing conversation. If omitted, a new conversation will be started." }, "stream": { "type": "boolean", "default": true, "description": "Whether to stream the response as Server-Sent Events (SSE). Defaults to true." }, "userId": { "type": "string", "maxLength": 128, "pattern": "^[a-zA-Z0-9._-]+$", "description": "Optional user ID to associate with a new conversation. Only applied when creating a new conversation (no conversationId). Once set, a conversation's userId is immutable — this field is ignored for existing conversations. Must contain only URL-safe characters (letters, digits, hyphens, underscores, dots)." } } }, "RetryRequest": { "type": "object", "properties": { "messageId": { "type": "string", "minLength": 1, "description": "The ID of the message to retry from", "example": "msg-abc123" }, "stream": { "type": "boolean", "default": true, "description": "Whether to stream the response as SSE. Defaults to true." } }, "required": [ "messageId" ] }, "VoiceSessionResponse": { "type": "object", "properties": { "participantToken": { "type": "string", "description": "Short-lived token scoped to this session. Pass the response `data` to the Chatbase Voice SDK in your client; safe to hand to the browser or mobile app." }, "sessionId": { "type": "string", "description": "The voice session ID." }, "roomName": { "type": "string", "description": "The session room name, for correlating logs." }, "maxDurationSeconds": { "type": "integer", "description": "Maximum session duration; the session ends automatically when it elapses." }, "conversationId": { "type": "string", "description": "The conversation this session belongs to (echoed or generated)." }, "userId": { "type": "string", "description": "The end-user ID for this session (echoed or generated)." } }, "required": [ "participantToken", "sessionId", "roomName", "maxDurationSeconds", "conversationId", "userId" ] }, "VoiceSessionRequest": { "type": "object", "properties": { "conversationId": { "type": "string", "format": "uuid", "description": "Optional conversation UUID. Reuse a value to group multiple voice sessions into one conversation in chat logs. If omitted, a new conversation is created. A conversation belongs to the end-user who started it: when reusing, send that same userId or omit userId to inherit it; a different userId is rejected with CONVERSATION_USER_MISMATCH." }, "userId": { "type": "string", "maxLength": 128, "pattern": "^[a-zA-Z0-9._-]+$", "description": "Your end-user ID. Send a stable ID so per-user voice limits apply; if omitted a random one is generated per session (or inherited from the conversation when reusing a conversationId). Sessions with the same userId but no conversationId are separate conversations owned by the same end-user. Must contain only URL-safe characters (letters, digits, hyphens, underscores, dots)." }, "timezone": { "type": "string", "maxLength": 64, "default": "UTC", "description": "IANA timezone of the end user (e.g. \"Europe/Paris\"), used by the agent for time-aware answers. Defaults to UTC." } } }, "ListConversationsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMetadata" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null if no more pages" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "total": { "type": "number", "description": "Total number of items matching the query" } }, "required": [ "cursor", "hasMore", "total" ] } }, "required": [ "data", "pagination" ] }, "ConversationMetadata": { "type": "object", "properties": { "id": { "type": "string", "description": "Conversation ID" }, "title": { "type": [ "string", "null" ], "description": "Conversation title" }, "createdAt": { "type": "number", "description": "Unix epoch timestamp (seconds)" }, "updatedAt": { "type": "number", "description": "Unix epoch timestamp (seconds) of last activity" }, "userId": { "type": [ "string", "null" ], "description": "User ID if the conversation is authenticated" }, "status": { "type": "string", "enum": [ "ongoing", "ended", "taken_over", "paused" ], "description": "Conversation activity status" }, "parentConversationId": { "type": [ "string", "null" ], "description": "ID of the parent conversation this was continued from, if any" }, "parentSummary": { "type": [ "string", "null" ], "description": "AI-generated summary of the parent conversation, if any" } }, "required": [ "id", "title", "createdAt", "updatedAt", "userId", "status", "parentConversationId", "parentSummary" ] }, "ExportConversationsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExportConversation" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null if no more pages" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "total": { "type": "number", "description": "Total number of items matching the query" } }, "required": [ "cursor", "hasMore", "total" ] } }, "required": [ "data", "pagination" ] }, "ExportConversation": { "type": "object", "properties": { "id": { "type": "string", "description": "Conversation ID" }, "title": { "type": [ "string", "null" ], "description": "Conversation title" }, "createdAt": { "type": "number", "description": "Unix epoch timestamp (seconds)" }, "updatedAt": { "type": "number", "description": "Unix epoch timestamp (seconds) of last activity" }, "userId": { "type": [ "string", "null" ], "description": "User ID if the conversation is authenticated" }, "source": { "type": [ "string", "null" ], "enum": [ "API", "WhatsApp", "Messenger", "Instagram", "Slack", "Salesforce", "Zendesk", "Zendesk Messaging", "Chatbase site", "Playground", "Action preview", "Qna preview", "Widget or Iframe", "Center stage", "Search", "Iframe", "Email", "Agent page", "Phone", "Android SDK", "iOS SDK", "Unspecified", null ], "description": "Conversation source" }, "embedOrigin": { "type": [ "string", "null" ], "description": "URL of the page the chat widget was embedded on when the conversation started, without its query string, e.g. `https://www.example.com/pricing`. Only the origin is included when the browser did not send the page path. Null when unknown or for non-widget conversations.", "example": "https://www.example.com/pricing" }, "status": { "type": "string", "enum": [ "ongoing", "ended", "taken_over", "paused" ], "description": "Conversation activity status" }, "parentConversationId": { "type": [ "string", "null" ], "description": "ID of the parent conversation this was continued from, if any" }, "parentSummary": { "type": [ "string", "null" ], "description": "AI-generated summary of the parent conversation, if any" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ExportMessage" }, "description": "Conversation messages. Present unless `include=summary` was requested." } }, "required": [ "id", "title", "createdAt", "updatedAt", "userId", "source", "embedOrigin", "status" ] }, "ExportMessage": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID" }, "role": { "type": "string", "enum": [ "user", "assistant" ], "description": "Message role" }, "parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool-call" ] }, "toolCallId": { "type": "string" }, "toolName": { "type": "string" } }, "required": [ "type", "toolCallId", "toolName" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tool-result" ] }, "toolCallId": { "type": "string" }, "toolName": { "type": "string" }, "output": {} }, "required": [ "type", "toolCallId", "toolName" ] } ] }, "description": "Message content parts" }, "createdAt": { "type": "number", "description": "Unix epoch timestamp (seconds)" }, "feedback": { "type": [ "string", "null" ], "enum": [ "positive", "negative", null ], "description": "User feedback on this message (present on assistant messages)" }, "metadata": { "$ref": "#/components/schemas/MessageMetadata" } }, "required": [ "id", "role", "parts" ] }, "MessageMetadata": { "type": "object", "properties": { "score": { "type": [ "number", "null" ], "description": "Confidence score for this message (0 to 1 float value)" } }, "required": [ "score" ], "description": "Message metadata (present on assistant messages)" }, "SearchConversationsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationSearchResult" } }, "pagination": { "$ref": "#/components/schemas/ConversationSearchPaginationMeta" } }, "required": [ "data", "pagination" ] }, "ConversationSearchResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Conversation ID" }, "title": { "type": [ "string", "null" ], "description": "Conversation title" }, "createdAt": { "type": "number", "description": "Unix epoch timestamp (seconds)" }, "updatedAt": { "type": "number", "description": "Unix epoch timestamp (seconds) of last activity" }, "userId": { "type": [ "string", "null" ], "description": "User ID if the conversation is authenticated" }, "source": { "type": [ "string", "null" ], "enum": [ "API", "WhatsApp", "Messenger", "Instagram", "Slack", "Salesforce", "Zendesk", "Zendesk Messaging", "Chatbase site", "Playground", "Action preview", "Qna preview", "Widget or Iframe", "Center stage", "Search", "Iframe", "Email", "Agent page", "Phone", "Android SDK", "iOS SDK", "Unspecified", null ], "description": "Conversation source" }, "embedOrigin": { "type": [ "string", "null" ], "description": "URL of the page the chat widget was embedded on when the conversation started, without its query string, e.g. `https://www.example.com/pricing`. Only the origin is included when the browser did not send the page path. Null when unknown or for non-widget conversations.", "example": "https://www.example.com/pricing" }, "status": { "type": "string", "enum": [ "ongoing", "ended", "taken_over", "paused" ], "description": "Conversation activity status" }, "parentConversationId": { "type": [ "string", "null" ], "description": "ID of the parent conversation this was continued from, if any" }, "parentSummary": { "type": [ "string", "null" ], "description": "AI-generated summary of the parent conversation, if any" }, "snippet": { "anyOf": [ { "$ref": "#/components/schemas/ConversationSearchSnippet" }, { "type": "null" } ], "description": "Best matching excerpt. Null when no `query` was given or the match was only in the title." } }, "required": [ "id", "title", "createdAt", "updatedAt", "userId", "source", "embedOrigin", "status", "snippet" ] }, "ConversationSearchSnippet": { "type": "object", "properties": { "speaker": { "type": "string", "enum": [ "user", "assistant" ], "description": "Who wrote the matching message" }, "highlights": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "isHit": { "type": "boolean", "description": "Whether this segment matched the query" } }, "required": [ "value", "isHit" ] }, "description": "The matching excerpt split into segments. Concatenate `value`s for the plain excerpt; segments with `isHit: true` matched the query." } }, "required": [ "speaker", "highlights" ] }, "ConversationSearchPaginationMeta": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null if no more pages" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" } }, "required": [ "cursor", "hasMore" ] }, "GetConversationResponse": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/ConversationMetadata" }, { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessage" } } }, "required": [ "messages" ] } ] }, "pagination": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null if no more pages" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "total": { "type": "number", "description": "Total number of items matching the query" } }, "required": [ "cursor", "hasMore", "total" ] } }, "required": [ "data", "pagination" ] }, "ConversationMessage": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID" }, "role": { "type": "string", "enum": [ "user", "assistant" ], "description": "Message role" }, "parts": { "allOf": [ { "$ref": "#/components/schemas/MessageParts" }, { "description": "Message content parts" } ] }, "createdAt": { "type": "number", "description": "Unix epoch timestamp (seconds)" }, "feedback": { "type": [ "string", "null" ], "enum": [ "positive", "negative", null ], "description": "User feedback on this message (present on assistant messages)" }, "metadata": { "$ref": "#/components/schemas/MessageMetadata" } }, "required": [ "id", "role", "parts" ] }, "ListMessagesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMessage" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null if no more pages" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "total": { "type": "number", "description": "Total number of items matching the query" } }, "required": [ "cursor", "hasMore", "total" ] } }, "required": [ "data", "pagination" ] }, "ListUserConversationsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationMetadata" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null if no more pages" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "total": { "type": "number", "description": "Total number of items matching the query" } }, "required": [ "cursor", "hasMore", "total" ] } }, "required": [ "data", "pagination" ] }, "UpdateConversationResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Conversation ID" }, "status": { "type": "string", "enum": [ "ongoing", "paused", "ended" ], "description": "Conversation activity status" } }, "required": [ "id", "status" ] } }, "required": [ "data" ] }, "UpdateConversationRequest": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ongoing", "paused", "ended" ], "description": "Target activity state for the conversation" } }, "required": [ "status" ], "additionalProperties": false }, "DeleteUserConversationsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deletedCount": { "type": "integer", "description": "Number of conversations deleted" }, "skippedCount": { "type": "integer", "description": "Number of conversations not deleted because their HIPAA processing has not finished. Retry later to delete them." } }, "required": [ "deletedCount", "skippedCount" ] } }, "required": [ "data" ] }, "UpdateMessageFeedbackResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ConversationMessage" } }, "required": [ "data" ] }, "UpdateMessageFeedbackRequest": { "type": "object", "properties": { "feedback": { "type": [ "string", "null" ], "enum": [ "positive", "negative", null ], "description": "Set feedback: \"positive\", \"negative\", or null to clear" } }, "required": [ "feedback" ], "additionalProperties": false }, "SubmitToolResultResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } }, "required": [ "data" ] }, "SubmitToolResultRequest": { "type": "object", "properties": { "toolCallId": { "type": "string", "minLength": 1, "description": "The toolCallId from the tool-call part in the chat response" }, "output": { "description": "The result of executing the tool action" } }, "required": [ "toolCallId" ], "additionalProperties": false }, "SourcesSummaryResponse": { "type": "object", "properties": { "links": { "$ref": "#/components/schemas/SourceTypeCount" }, "files": { "allOf": [ { "$ref": "#/components/schemas/SourceTypeCount" }, { "description": "Aggregated stats for file sources" } ] }, "qnas": { "allOf": [ { "$ref": "#/components/schemas/SourceTypeCount" }, { "description": "Aggregated stats for Q&A sources" } ] }, "notionPages": { "allOf": [ { "$ref": "#/components/schemas/SourceTypeCount" }, { "description": "Aggregated stats for Notion sources" } ] }, "texts": { "allOf": [ { "$ref": "#/components/schemas/SourceTypeCount" }, { "description": "Aggregated stats for text sources" } ] }, "zendeskTickets": { "allOf": [ { "$ref": "#/components/schemas/SourceTypeCount" }, { "description": "Aggregated stats for Zendesk ticket sources. count = total number of ticket IDs tracked" } ] }, "salesforceCases": { "allOf": [ { "$ref": "#/components/schemas/SourceTypeCount" }, { "description": "Aggregated stats for Salesforce case sources. count = total number of case IDs tracked" } ] }, "shouldRetrain": { "type": "boolean", "description": "True when the agent knowledge base requires a retrain to reflect any changes" } }, "required": [ "links", "files", "qnas", "notionPages", "texts", "zendeskTickets", "salesforceCases", "shouldRetrain" ] }, "SourceTypeCount": { "type": "object", "properties": { "count": { "type": "number", "description": "Number of sources" }, "size": { "type": "number", "description": "Total size in bytes" } }, "required": [ "count", "size" ], "description": "Aggregated stats for link sources" }, "ListSourcesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SourceListItem" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null if no more pages" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "total": { "type": "number", "description": "Total number of items matching the query" } }, "required": [ "cursor", "hasMore", "total" ] } }, "required": [ "data", "pagination" ] }, "SourceListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Source ID" }, "type": { "type": "string", "enum": [ "link", "file", "qna", "notionPage", "text" ], "description": "Source type" }, "name": { "type": [ "string", "null" ], "description": "Source name or URL" }, "size": { "type": "number", "description": "Source size in bytes" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp" }, "status": { "type": "string", "enum": [ "untrained", "trained", "toBeDeleted", "updated", "failed" ], "description": "Training status of the source. `failed` means the last training run did not land; an earlier trained version, if any, stays live." }, "metadata": { "$ref": "#/components/schemas/LinkMetadata" } }, "required": [ "id", "type", "name", "size", "createdAt", "status", "metadata" ] }, "LinkMetadata": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "individual" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "crawl", "sitemap" ] }, "excludePaths": { "type": "array", "items": { "type": "string" }, "description": "Regex patterns for excluded URL paths" }, "includeOnlyPaths": { "type": "array", "items": { "type": "string" }, "description": "Regex patterns for included URL paths" }, "slowScraping": { "type": "boolean", "description": "Whether slow scraping mode is enabled" }, "crawlStatus": { "type": "string", "enum": [ "fetching", "fetched", "failed" ], "description": "Crawl progress status." }, "children": { "$ref": "#/components/schemas/LinkChildren" } }, "required": [ "type", "excludePaths", "includeOnlyPaths", "slowScraping", "crawlStatus", "children" ] }, { "type": "null" } ], "description": "Link-specific metadata. Present only for type=\"link\"." }, "LinkChildren": { "type": "object", "properties": { "included": { "type": "number", "description": "Non-excluded, non-failed links" }, "excluded": { "type": "number", "description": "Explicitly excluded links" }, "failed": { "type": "number", "description": "Failed or discarded links" } }, "required": [ "included", "excluded", "failed" ], "description": "Child link counts" }, "DeletedSourceListItem": { "allOf": [ { "$ref": "#/components/schemas/SourceListItem" }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "untrained", "trained", "toBeDeleted", "updated", "failed", "deleted" ], "description": "Training status of the source" } } } ] }, "CreateSourceBody": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "content": { "type": "string", "minLength": 1, "maxLength": 1048576 } }, "required": [ "type", "name", "content" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "qna" ] }, "name": { "type": "string", "minLength": 1 }, "questions": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50 }, "answer": { "type": "string", "minLength": 1 } }, "required": [ "type", "name", "questions", "answer" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "link" ] }, "url": { "type": "string", "format": "uri" }, "linkType": { "type": "string", "enum": [ "individual", "sitemap", "crawl" ] }, "excludePaths": { "type": "array", "items": { "type": "string" }, "default": [] }, "includeOnlyPaths": { "type": "array", "items": { "type": "string" }, "default": [] }, "slowScraping": { "type": "boolean", "default": false } }, "required": [ "type", "url", "linkType" ] } ] }, "UpdateSourceBody": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "content": { "type": "string", "minLength": 1, "maxLength": 1048576 } } }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "questions": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 50 }, "answer": { "type": "string", "minLength": 1 } } }, { "type": "object", "properties": { "excludePaths": { "type": "array", "items": { "type": "string" } }, "includeOnlyPaths": { "type": "array", "items": { "type": "string" } }, "slowScraping": { "type": "boolean" } } } ] }, "ListWhatsAppTemplatesResponse": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsAppTemplate" } }, "complete": { "type": "boolean", "description": "False when at least one of the agent’s WhatsApp Business Accounts could not be read. The list is then partial and must not be treated as the full set." }, "unavailableWabaIds": { "type": "array", "items": { "type": "string" }, "description": "WhatsApp Business Account IDs whose templates could not be fetched. Retry to pick them up.", "example": [] }, "senders": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsAppSender" }, "description": "The agent’s connected WhatsApp numbers. Pick one whose `wabaId` matches the template’s `wabaId` and pass its `from` value to the send endpoint." } }, "required": [ "templates", "complete", "unavailableWabaIds", "senders" ] }, "WhatsAppTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "Meta template ID" }, "name": { "type": "string", "description": "Template name" }, "language": { "type": "string", "description": "Language code (e.g. `en_US`)" }, "category": { "type": "string", "description": "Template category (MARKETING, UTILITY, AUTHENTICATION)" }, "status": { "type": "string", "description": "Meta review status (APPROVED)" }, "parameterFormat": { "type": "string", "enum": [ "POSITIONAL", "NAMED" ], "description": "Whether variables are positional (`{{1}}`) or named (`{{name}}`)" }, "wabaId": { "type": "string", "description": "WhatsApp Business Account ID this template belongs to" }, "variables": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Variable keys the template expects, grouped by component and in order of appearance — the same shape `template.variables` takes on the send endpoint. Supply a value for every key listed.", "example": { "header": [ "1" ], "body": [ "1", "2" ] } }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsAppTemplateComponent" }, "description": "Template components as approved by Meta" } }, "required": [ "id", "name", "language", "category", "status", "parameterFormat", "wabaId", "variables", "components" ] }, "WhatsAppTemplateComponent": { "type": "object", "properties": { "type": { "type": "string", "description": "Component type (HEADER, BODY, FOOTER, BUTTONS)" }, "format": { "type": "string", "description": "Header format when type is HEADER (TEXT, IMAGE, VIDEO, DOCUMENT)" }, "text": { "type": "string", "description": "Component text with `{{...}}` variable placeholders, when applicable" }, "buttons": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsAppTemplateButton" } } }, "required": [ "type" ] }, "WhatsAppTemplateButton": { "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" }, "url": { "type": "string", "description": "Destination of a URL button. A `{{...}}` placeholder here means the button takes a parameter, which the send endpoint cannot supply — sending such a template returns `TEMPLATE_BUTTONS_UNSUPPORTED`." } }, "required": [ "type" ] }, "WhatsAppSender": { "type": "object", "properties": { "from": { "type": "string", "description": "Value to pass as `from` when sending. Formatting is ignored when matching.", "example": "14155552671" }, "wabaId": { "type": "string", "description": "WhatsApp Business Account this number belongs to. Only templates whose `wabaId` matches can be sent from it." }, "verifiedName": { "type": [ "string", "null" ], "description": "Display name Meta verified for this number" } }, "required": [ "from", "wabaId", "verifiedName" ] }, "SendWhatsAppTemplateResponse": { "type": "object", "properties": { "messageId": { "type": [ "string", "null" ], "description": "WhatsApp message ID (wamid) of the sent message" }, "conversationId": { "type": [ "string", "null" ], "description": "Chatbase conversation the recipient’s replies continue in. The message is also appended to that conversation, unless a human has taken it over or it has ended — in those cases only the WhatsApp delivery happens." }, "to": { "type": "string", "description": "Canonical recipient WhatsApp ID the message was sent to" } }, "required": [ "messageId", "conversationId", "to" ] }, "SendWhatsAppTemplateBody": { "type": "object", "properties": { "to": { "type": "string", "minLength": 1, "description": "Recipient phone number in international format (digits with country code, `+` and separators are tolerated). The phone number is the recipient identity: no user ID is needed — a Chatbase user is automatically resolved or created from this number (matching an existing contact with the same phone when one exists), and replies continue in that user’s conversation.", "example": "14155552671" }, "from": { "type": "string", "minLength": 1, "description": "Which of the agent’s connected WhatsApp business numbers to send from, in international format. Formatting is ignored when matching, so `+1 415-555-2671` and `14155552671` are equivalent. Optional when the agent has exactly one connected number.", "example": "14155552671" }, "template": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Name of the approved template", "example": "order_confirmation" }, "language": { "type": "string", "minLength": 1, "description": "Template language code (e.g. `en_US`). Optional when the template exists in a single language.", "example": "en_US" }, "variables": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string" } }, "default": {}, "description": "Values for the template variables, grouped by component (`header`, `body`) — the same grouping WhatsApp uses when it sends. Each component numbers its own placeholders from `{{1}}`, so a text header and the body can each declare a `{{1}}`; keeping them under separate keys is what tells the two apart. For a named template use the parameter names instead of numbers. The `variables` object on the list-templates response reports exactly which keys each component expects.", "example": { "header": { "1": "#1042" }, "body": { "1": "Jane", "2": "Friday" } } } }, "required": [ "name" ] } }, "required": [ "to", "template" ], "example": { "to": "14155552671", "from": "14155552672", "template": { "name": "order_update", "language": "en_US", "variables": { "header": { "1": "#1042" }, "body": { "1": "Jane", "2": "Friday" } } } } }, "TicketStatusList": { "type": "array", "items": { "$ref": "#/components/schemas/TicketStatus" } }, "TicketStatus": { "type": "object", "properties": { "id": { "type": "string", "description": "Status ID" }, "category": { "type": "string", "enum": [ "new", "on_you", "on_customer", "on_hold", "closed", "cancelled" ], "description": "Status category. Controls the status color and ordering." }, "externalLabel": { "type": "string", "description": "Customer-facing status label", "example": "In progress" }, "internalLabel": { "type": "string", "description": "Agent-facing status label shown in the dashboard", "example": "In progress" }, "color": { "type": [ "string", "null" ], "description": "Hex color associated with this status", "example": "#2563EB" }, "isDefault": { "type": "boolean", "description": "Whether this is the default status for its category" }, "position": { "type": "integer", "description": "Ordering position within the status category" } }, "required": [ "id", "category", "externalLabel", "internalLabel", "color", "isDefault", "position" ] }, "TeamListResponse": { "type": "array", "items": { "$ref": "#/components/schemas/TeamListItem" } }, "TeamListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" }, "isDefault": { "type": "boolean", "description": "Whether this is the default team for the agent" }, "memberCount": { "type": "integer", "minimum": 0, "description": "Number of members assigned to this team" } }, "required": [ "id", "name", "isDefault", "memberCount" ] }, "AttendanceRowListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttendanceRow" } }, "pagination": { "$ref": "#/components/schemas/HelpdeskReportPagination" } }, "required": [ "data", "pagination" ] }, "AttendanceRow": { "type": "object", "properties": { "date": { "type": "string", "description": "Calendar day of the row in `timezone`", "example": "2026-10-29" }, "operator": { "$ref": "#/components/schemas/AttendanceOperator" }, "teams": { "type": "array", "items": { "$ref": "#/components/schemas/AttendanceTeam" }, "description": "Teams the operator belongs to. Empty when the operator is in no team." }, "shiftNumber": { "type": "integer", "exclusiveMinimum": 0, "description": "Position of the row among the operator's rows for this day, starting at 1. The export calls it Shift 1, Shift 2 when there is more than one." }, "shiftCount": { "type": "integer", "exclusiveMinimum": 0, "description": "How many rows the operator has on this day: one per part of a shift that falls on it, plus one for time logged outside those parts" }, "shiftName": { "type": [ "string", "null" ], "description": "Name of the operator's shift on a row for part of that shift or for planned time off, or null on a row of time logged outside the shift" }, "scheduledStart": { "type": [ "string", "null" ], "description": "ISO 8601 start of the part of the shift this row covers, or null on a row without scheduled time", "example": "2026-10-29T07:00:00.000Z" }, "scheduledEnd": { "type": [ "string", "null" ], "description": "ISO 8601 end of the part of the shift this row covers, or null on a row without scheduled time", "example": "2026-10-29T07:00:00.000Z" }, "timeScheduledMinutes": { "type": [ "integer", "null" ], "description": "Length of the scheduled part of the shift on this day, in minutes" }, "loggedStart": { "type": [ "string", "null" ], "description": "ISO 8601 start of the first session on this row, or null when there is none", "example": "2026-10-29T07:00:00.000Z" }, "loggedEnd": { "type": [ "string", "null" ], "description": "ISO 8601 end of the last session on this row, or null when there is none", "example": "2026-10-29T07:00:00.000Z" }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "description": "ISO 8601 start of the session" }, "end": { "type": "string", "description": "ISO 8601 end of the session" } }, "required": [ "start", "end" ] }, "description": "Each continuous stretch the operator was logged in. A gap of 2 minutes or less does not split a session, unless the operator was idle in it." }, "timeLoggedMinutes": { "type": [ "integer", "null" ], "description": "Total of all sessions, in minutes" }, "productiveTimeMinutes": { "type": [ "integer", "null" ], "description": "Part of the logged time spent on tickets, in minutes" }, "breaksMinutes": { "type": [ "integer", "null" ], "description": "Time between sessions inside the scheduled hours, idle time included, in minutes" }, "lateMinutes": { "type": [ "integer", "null" ], "description": "How long after the scheduled start the first session began, in minutes" }, "leftEarlyMinutes": { "type": [ "integer", "null" ], "description": "How long before the scheduled end the last session ended, in minutes. Null until that end has passed." }, "overtimeMinutes": { "type": [ "integer", "null" ], "description": "Time logged outside the scheduled hours, in minutes" }, "unplannedTimeOff": { "type": "boolean", "description": "Whether the shift started and the operator never logged in for it" }, "plannedTimeOff": { "type": "boolean", "description": "Whether time off from Scheduling covers a shift that would have fallen on this day. Such a day gets its own row." }, "occupancyPercent": { "type": [ "number", "null" ], "description": "Productive time divided by time logged, as a percentage" }, "adherencePercent": { "type": [ "number", "null" ], "description": "Time logged inside the scheduled hours divided by time scheduled, as a percentage. At most 100." }, "conformancePercent": { "type": [ "number", "null" ], "description": "Time logged divided by time scheduled, as a percentage. Overtime counts, so it can go above 100." }, "utilizationPercent": { "type": [ "number", "null" ], "description": "Productive time divided by time scheduled, as a percentage" } }, "required": [ "date", "operator", "teams", "shiftNumber", "shiftCount", "shiftName", "scheduledStart", "scheduledEnd", "timeScheduledMinutes", "loggedStart", "loggedEnd", "sessions", "timeLoggedMinutes", "productiveTimeMinutes", "breaksMinutes", "lateMinutes", "leftEarlyMinutes", "overtimeMinutes", "unplannedTimeOff", "plannedTimeOff", "occupancyPercent", "adherencePercent", "conformancePercent", "utilizationPercent" ] }, "AttendanceOperator": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID of the operator" }, "name": { "type": "string", "description": "Operator name" }, "email": { "type": "string", "description": "Operator email" } }, "required": [ "id", "name", "email" ] }, "AttendanceTeam": { "type": "object", "properties": { "id": { "type": "string", "description": "Team ID" }, "name": { "type": "string", "description": "Team name" } }, "required": [ "id", "name" ] }, "HelpdeskReportPagination": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null if no more pages" }, "hasMore": { "type": "boolean", "description": "Whether more pages follow" } }, "required": [ "cursor", "hasMore" ] }, "ActivitySegmentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivitySegment" } }, "pagination": { "$ref": "#/components/schemas/HelpdeskReportPagination" } }, "required": [ "data", "pagination" ] }, "ActivitySegment": { "type": "object", "properties": { "id": { "type": "string", "description": "Segment ID" }, "operator": { "$ref": "#/components/schemas/AttendanceOperator" }, "kind": { "type": "string", "enum": [ "ticket", "untracked", "idle" ], "description": "`ticket` while a ticket was open, `untracked` while logged in without a ticket open, `idle` after 10 minutes without input" }, "ticketNumber": { "type": [ "integer", "null" ], "description": "Ticket number for a `ticket` segment, or null for other kinds and for deleted tickets" }, "startedAt": { "type": "string", "description": "ISO 8601 time the segment started", "example": "2026-10-29T07:02:13.418Z" }, "lastSeenAt": { "type": "string", "description": "ISO 8601 time the segment was last refreshed. An open segment is refreshed every few minutes while the operator is active.", "example": "2026-10-29T07:16:40.102Z" }, "endedAt": { "type": [ "string", "null" ], "description": "ISO 8601 time the segment ended, or null while it is still open", "example": "2026-10-29T07:17:05.733Z" } }, "required": [ "id", "operator", "kind", "ticketNumber", "startedAt", "lastSeenAt", "endedAt" ] }, "Ticket": { "type": "object", "properties": { "ticketNumber": { "type": "integer", "description": "The ticket number", "example": 123 }, "subject": { "type": [ "string", "null" ], "description": "Ticket subject" }, "description": { "type": [ "string", "null" ], "description": "Ticket description" }, "statusCategory": { "type": "string", "enum": [ "new", "on_you", "on_customer", "on_hold", "closed", "cancelled" ], "description": "Status category driving color/ordering semantics", "example": "on_customer" }, "statusId": { "type": "string", "description": "ID of the ticket status. Resolve label/color via /ticket-statuses." }, "assigneeId": { "type": [ "string", "null" ], "description": "ID of the assigned agent user, or null when unassigned" }, "customer": { "$ref": "#/components/schemas/TicketCustomer" }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Arbitrary extra fields captured on the ticket", "example": { "phone_number": "+1 525-525-5255" } }, "channel": { "type": "string", "enum": [ "helpdesk", "iframe", "email", "whatsapp", "api", "messenger", "instagram", "center_stage", "phone", "instagram_comment", "facebook_comment" ], "description": "Channel the ticket originated from", "example": "email" }, "conversationId": { "type": [ "string", "null" ], "description": "ID of the linked conversation, if any" }, "teamId": { "type": [ "string", "null" ], "description": "ID of the assigned team, or null. Resolve via /teams." }, "priority": { "type": "string", "enum": [ "none", "low", "normal", "high", "urgent" ], "description": "Ticket priority. `none` means the ticket has not been triaged.", "example": "high" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp", "example": "2026-07-20T12:34:56.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp of the last update", "example": "2026-07-21T09:00:00.000Z" }, "lastMessageAt": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the most recent message, or null if the ticket has no messages", "example": "2026-07-21T08:55:00.000Z" } }, "required": [ "ticketNumber", "subject", "description", "statusCategory", "statusId", "assigneeId", "customer", "metadata", "channel", "conversationId", "teamId", "priority", "createdAt", "updatedAt", "lastMessageAt" ] }, "TicketCustomer": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the customer participant" }, "name": { "type": [ "string", "null" ], "description": "Customer display name, or null when not captured", "example": "Ada Lovelace" }, "email": { "type": [ "string", "null" ], "description": "Customer email, or null when not captured", "example": "ada@example.com" }, "phoneNumber": { "type": [ "string", "null" ], "description": "Customer phone number, or null when not captured" } }, "required": [ "id", "name", "email", "phoneNumber" ] }, "CreateTicketBody": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Ticket subject (1-500 characters)", "example": "Export failing with 500" }, "description": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "The first message body, written as a reply authored by the customer (1-10,000 characters)", "example": "Customer cannot export orders." }, "customer": { "$ref": "#/components/schemas/CreateTicketCustomer" }, "statusId": { "type": "string", "format": "uuid", "description": "ID of an existing status for this agent. Provide at most one of statusId / statusCategory." }, "statusCategory": { "type": "string", "enum": [ "new", "on_you", "on_customer", "on_hold", "closed", "cancelled" ], "description": "Status category; resolves to that category's default status. Provide at most one of statusId / statusCategory. Defaults to the \"new\" category default when neither is provided.", "example": "new" }, "assigneeId": { "type": [ "string", "null" ], "format": "uuid", "description": "Platform user id of the agent to assign. Provide at most one of assigneeId / assigneeEmail. Pass `null` to explicitly create the ticket unassigned (suppresses auto-assignment); omit to let auto-assignment apply." }, "assigneeEmail": { "type": "string", "format": "email", "description": "Email of the agent to assign (case-insensitive). Provide at most one of assigneeId / assigneeEmail.", "example": "sam@example.com" }, "teamId": { "type": "string", "format": "uuid", "description": "ID of an existing team for this agent. When provided without any assignee field, an agent is picked within this team using the team's own assignment strategy, and routing rules are skipped. When provided together with assigneeId/assigneeEmail, including assigneeId: null, no auto-assignment runs and the team is written as given." }, "priority": { "type": "string", "enum": [ "none", "low", "normal", "high", "urgent" ], "description": "Ticket priority. Defaults to `none` (untriaged) when omitted.", "example": "high" } }, "required": [ "subject", "description", "customer" ] }, "CreateTicketCustomer": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Resolves to an existing chatbot_users row for this agent, or creates one", "example": "jane@example.com" }, "name": { "type": "string", "maxLength": 255, "description": "Used only when creating a new customer record; ignored if the email already resolves", "example": "Jane Doe" } }, "required": [ "email" ] }, "SearchTicketsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SearchTicketsItem" } }, "pagination": { "$ref": "#/components/schemas/SearchTicketsPaginationMeta" } }, "required": [ "data", "pagination" ] }, "SearchTicketsItem": { "type": "object", "properties": { "ticketNumber": { "type": "integer", "description": "The ticket number", "example": 123 }, "subject": { "type": [ "string", "null" ], "description": "Ticket subject" }, "statusCategory": { "type": "string", "enum": [ "new", "on_you", "on_customer", "on_hold", "closed", "cancelled" ], "description": "Status category driving color/ordering semantics", "example": "on_customer" }, "statusId": { "type": "string", "description": "ID of the ticket status. Resolve label/color via /ticket-statuses." }, "assigneeId": { "type": [ "string", "null" ], "description": "ID of the assigned agent user, or null when unassigned" }, "customer": { "$ref": "#/components/schemas/TicketCustomer" }, "channel": { "type": "string", "enum": [ "helpdesk", "iframe", "email", "whatsapp", "api", "messenger", "instagram", "center_stage", "phone", "instagram_comment", "facebook_comment" ], "description": "Channel the ticket originated from", "example": "email" }, "conversationId": { "type": [ "string", "null" ], "description": "ID of the linked conversation, if any" }, "teamId": { "type": [ "string", "null" ], "description": "ID of the assigned team, or null. Resolve via /teams." }, "priority": { "type": "string", "enum": [ "none", "low", "normal", "high", "urgent" ], "description": "Ticket priority. `none` means the ticket has not been triaged.", "example": "high" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp", "example": "2026-07-20T12:34:56.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp of the last update", "example": "2026-07-21T09:00:00.000Z" }, "lastMessageAt": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the most recent message, or null if the ticket has no messages", "example": "2026-07-21T08:55:00.000Z" } }, "required": [ "ticketNumber", "subject", "statusCategory", "statusId", "assigneeId", "customer", "channel", "conversationId", "teamId", "priority", "createdAt", "updatedAt", "lastMessageAt" ] }, "SearchTicketsPaginationMeta": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Opaque continuation token. Null while search results are not paginated." }, "hasMore": { "type": "boolean", "description": "Whether more matches exist beyond the returned window. Refine the query to narrow it." } }, "required": [ "cursor", "hasMore" ] }, "SearchTicketsBody": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Free-text search terms, matched against ticket messages.", "example": "refund not received" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "Number of results to return (1 to 50, default 20)", "example": 20 } }, "required": [ "query" ] }, "ListTicketsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TicketListItem" } }, "pagination": { "$ref": "#/components/schemas/TicketListPaginationMeta" } }, "required": [ "data", "pagination" ] }, "TicketListItem": { "type": "object", "properties": { "ticketNumber": { "type": "integer", "description": "The ticket number", "example": 123 }, "subject": { "type": [ "string", "null" ], "description": "Ticket subject" }, "statusCategory": { "type": "string", "enum": [ "new", "on_you", "on_customer", "on_hold", "closed", "cancelled" ], "description": "Status category driving color/ordering semantics", "example": "on_customer" }, "statusId": { "type": "string", "description": "ID of the ticket status. Resolve label/color via /ticket-statuses." }, "assigneeId": { "type": [ "string", "null" ], "description": "ID of the assigned agent user, or null when unassigned" }, "customer": { "$ref": "#/components/schemas/TicketCustomer" }, "channel": { "type": "string", "enum": [ "helpdesk", "iframe", "email", "whatsapp", "api", "messenger", "instagram", "center_stage", "phone", "instagram_comment", "facebook_comment" ], "description": "Channel the ticket originated from", "example": "email" }, "conversationId": { "type": [ "string", "null" ], "description": "ID of the linked conversation, if any" }, "teamId": { "type": [ "string", "null" ], "description": "ID of the assigned team, or null. Resolve via /teams." }, "priority": { "type": "string", "enum": [ "none", "low", "normal", "high", "urgent" ], "description": "Ticket priority. `none` means the ticket has not been triaged.", "example": "high" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp", "example": "2026-07-20T12:34:56.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp of the last update", "example": "2026-07-21T09:00:00.000Z" }, "lastMessageAt": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of the most recent message, or null if the ticket has no messages", "example": "2026-07-21T08:55:00.000Z" }, "messages": { "$ref": "#/components/schemas/ListTicketMessagesResponse" } }, "required": [ "ticketNumber", "subject", "statusCategory", "statusId", "assigneeId", "customer", "channel", "conversationId", "teamId", "priority", "createdAt", "updatedAt", "lastMessageAt" ] }, "ListTicketMessagesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null if no more pages" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "total": { "type": "number", "description": "Total number of items matching the query" } }, "required": [ "cursor", "hasMore", "total" ] } }, "required": [ "data", "pagination" ] }, "Message": { "type": "object", "properties": { "id": { "type": "string", "description": "Message id" }, "type": { "type": "string", "enum": [ "reply", "note", "event" ], "description": "`reply` is customer-visible, `note` is an internal note, `event` is a system timeline entry", "example": "reply" }, "sender": { "$ref": "#/components/schemas/MessageSender" }, "content": { "type": [ "string", "null" ], "description": "Rich (HTML) body. Null on `event` messages." }, "contentText": { "type": [ "string", "null" ], "description": "Plain-text body. Null on `event` messages." }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/MessageAttachment" }, "description": "Always an empty array on `event` messages" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp", "example": "2026-07-25T10:15:00.000Z" }, "metadata": { "$ref": "#/components/schemas/MessageEventMetadata" } }, "required": [ "id", "type", "sender", "content", "contentText", "attachments", "createdAt" ] }, "MessageSender": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "customer", "agent", "system" ], "description": "Who sent the message", "example": "customer" }, "id": { "type": [ "string", "null" ], "description": "Sender id: a platform user id for agents, a contact id for customers" }, "name": { "type": [ "string", "null" ], "description": "Sender name" }, "email": { "type": [ "string", "null" ], "description": "Sender email" } }, "required": [ "type", "id", "name", "email" ], "description": "Null on `event` messages" }, "MessageAttachment": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "File name" }, "url": { "type": [ "string", "null" ], "description": "Download URL. The route is unauthenticated and the token in the path is the secret. It redirects to a URL signed for 120 seconds, so it cannot be cached. Null when the stored attachment has no token." }, "type": { "type": [ "string", "null" ], "description": "MIME type", "example": "application/pdf" }, "size": { "type": [ "number", "null" ], "description": "Size in bytes" } }, "required": [ "name", "url", "type", "size" ] }, "MessageEventMetadata": { "type": "object", "properties": { "eventType": { "type": [ "string", "null" ], "description": "Event kind: `status_change`, `assign`, `field_change`, `priority_change`, `team_change`, `tag_added`, `tag_removed`, `email_sent`, `webhook_sent` or `slack_sent`. Other values may appear as new event kinds are added, and carry only the common fields.", "example": "status_change" }, "doneBy": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "agent", "customer", null ], "description": "Whether the actor is one of your agents or the ticket customer" } }, "required": [ "id", "name", "email", "type" ], "description": "Who made the change. Null for automatic changes, including trigger changes." }, "triggerId": { "type": [ "string", "null" ], "description": "Id of the trigger that made the change. Null when no trigger did, or the trigger was since deleted." }, "triggerName": { "type": [ "string", "null" ], "description": "Name of the trigger that made the change, as it was named at the time. Null when no trigger did." }, "runId": { "type": [ "string", "null" ], "description": "Id of the trigger run. Events from the same run share it. Null when no trigger made the change." }, "statusFrom": { "type": [ "string", "null" ], "description": "Previous status category (status_change only)", "example": "on_you" }, "statusTo": { "type": [ "string", "null" ], "description": "New status category (status_change only)", "example": "closed" }, "assignedTo": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "agent", "customer", null ], "description": "Whether the actor is one of your agents or the ticket customer" } }, "required": [ "id", "name", "email", "type" ], "description": "New assignee (assign only)" }, "assignedFrom": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "enum": [ "agent", "customer", null ], "description": "Whether the actor is one of your agents or the ticket customer" } }, "required": [ "id", "name", "email", "type" ], "description": "Previous assignee (assign only)" }, "fieldId": { "type": [ "string", "null" ], "description": "Custom ticket field id (field_change only)" }, "fieldLabel": { "type": [ "string", "null" ], "description": "Custom ticket field label when the change happened (field_change only)" }, "valueFrom": { "type": [ "string", "null" ], "description": "Previous field value (field_change only)" }, "valueTo": { "type": [ "string", "null" ], "description": "New field value (field_change only)" }, "priorityFrom": { "type": [ "string", "null" ], "description": "Previous priority (priority_change only)" }, "priorityTo": { "type": [ "string", "null" ], "description": "New priority (priority_change only)" }, "teamFrom": { "type": [ "string", "null" ], "description": "Previous team id (team_change only)" }, "teamTo": { "type": [ "string", "null" ], "description": "New team id (team_change only)" }, "teamFromName": { "type": [ "string", "null" ], "description": "Previous team name when the change happened (team_change only)" }, "teamToName": { "type": [ "string", "null" ], "description": "New team name when the change happened (team_change only)" }, "tagId": { "type": [ "string", "null" ], "description": "Tag id (tag_added / tag_removed only)" }, "tagName": { "type": [ "string", "null" ], "description": "Tag name when the change happened (tag_added / tag_removed only)" }, "emailTo": { "type": [ "string", "null" ], "description": "Recipient: an email address, or the recipient role such as `requester` (email_sent only)" }, "emailSubject": { "type": [ "string", "null" ], "description": "Email subject (email_sent only)" }, "webhookId": { "type": [ "string", "null" ], "description": "Webhook id (webhook_sent only)" }, "deliveryStatus": { "type": [ "string", "null" ], "enum": [ "pending", "delivered", "failed", null ], "description": "Webhook delivery outcome (webhook_sent only). `pending` until the endpoint responds." }, "statusCode": { "type": [ "integer", "null" ], "description": "HTTP status the endpoint returned (webhook_sent only). Null while pending, or when the delivery timed out or could not connect." }, "slackChannels": { "type": "array", "items": { "type": "string" }, "description": "Slack channel names the message was posted to (slack_sent only)" } }, "required": [ "eventType" ], "description": "Present only on `event` messages" }, "TicketListPaginationMeta": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null if no more pages" }, "hasMore": { "type": "boolean", "description": "Whether more results are available" }, "total": { "type": "integer", "description": "Total number of tickets matching the filters. Present only when `includeTotal=true`." } }, "required": [ "cursor", "hasMore" ] }, "CreatedTicketMessage": { "type": "object", "properties": { "id": { "type": "string", "description": "Message id" }, "type": { "type": "string", "enum": [ "reply" ], "description": "Message type", "example": "reply" }, "sender": { "allOf": [ { "$ref": "#/components/schemas/MessageSender" }, { "description": "The team member the reply is attributed to" } ] }, "content": { "type": "string", "description": "Rendered, sanitized HTML body" }, "contentText": { "type": "string", "description": "The raw markdown body as submitted" }, "createdAt": { "type": "string", "description": "ISO 8601 creation timestamp", "example": "2026-07-29T09:00:00.000Z" } }, "required": [ "id", "type", "sender", "content", "contentText", "createdAt" ] }, "CreateTicketMessageBody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reply" ], "description": "Message type. Only `reply` (customer-visible, delivered to the customer) is supported.", "example": "reply" }, "content": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Message body as GitHub-flavored Markdown. Plain text is valid markdown; single newlines are kept as line breaks. Raw inline HTML is stripped. Limited to 10,000 characters after trimming.", "example": "Thanks for reaching out. This is **fixed** now." }, "authorId": { "type": "string", "format": "uuid", "description": "Platform user id of the team member the reply is attributed to. Provide exactly one of authorId / authorEmail." }, "authorEmail": { "type": "string", "format": "email", "description": "Email of the team member the reply is attributed to (case-insensitive). Provide exactly one of authorId / authorEmail.", "example": "sam@example.com" } }, "required": [ "type", "content" ] }, "UpdateTicketBody": { "type": "object", "properties": { "statusId": { "type": "string", "format": "uuid", "description": "ID of an existing status for this agent. Provide at most one of statusId / statusCategory. Omit to leave the status unchanged." }, "statusCategory": { "type": "string", "enum": [ "new", "on_you", "on_customer", "on_hold", "closed", "cancelled" ], "description": "Status category; resolves to that category's default status. Provide at most one of statusId / statusCategory. Omit to leave the status unchanged.", "example": "on_customer" }, "assigneeId": { "type": [ "string", "null" ], "format": "uuid", "description": "Platform user id of the agent to assign. Provide at most one of assigneeId / assigneeEmail. Pass null to unassign the ticket. Omit to leave the assignee unchanged." }, "assigneeEmail": { "type": "string", "format": "email", "description": "Email of the agent to assign (case-insensitive). Provide at most one of assigneeId / assigneeEmail. Does not accept null; unassign via assigneeId: null. Omit to leave the assignee unchanged.", "example": "sam@example.com" }, "teamId": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of an existing team for this agent. Pass null to clear the team. Omit to leave the team unchanged." }, "priority": { "type": "string", "enum": [ "none", "low", "normal", "high", "urgent" ], "description": "New ticket priority. Pass `none` to clear it. Omit to leave the priority unchanged.", "example": "urgent" }, "agentEmail": { "type": "string", "format": "email", "description": "Optional. Attribute this change to the agent with this email — a member of this account (case-insensitive). If omitted, or the email is not a recognized member, the change is recorded as an automatic system change. Not itself a change: you must still provide at least one field above.", "example": "sam@example.com" } } } }, "parameters": {} }, "paths": { "/health": { "get": { "operationId": "getHealth", "tags": [ "Health" ], "summary": "Health check", "description": "Returns the API health status. No authentication required.", "responses": { "200": { "description": "API is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "timestamp": { "$ref": "#/components/schemas/UnixTimestamp" } }, "required": [ "status", "timestamp" ] }, "example": { "status": "ok", "timestamp": 1770681600 } } } } } } }, "/agents": { "get": { "operationId": "listAgents", "x-mcp": { "tool": "chatbase_list_agents", "scopes": [ "agents:read" ], "annotations": { "readOnly": true, "idempotent": true }, "fields": [ "id", "name", "status", "createdAt", "model", "autoRetrain", "lastTrainedAt", "lastMessageAt", "size", "visibility", "temp", "creditLimit", "creditsUsed" ], "maxItems": 25 }, "tags": [ "Agents" ], "summary": "List agents", "description": "Returns a paginated list of all agents for the authenticated account.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Opaque cursor from a previous response to fetch the next page", "example": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items per page (1 to 100, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1 to 100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Paginated list of agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAgentsResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } }, "post": { "operationId": "createAgent", "x-mcp": { "tool": "chatbase_create_agent", "scopes": [ "agents:write" ], "annotations": {} }, "tags": [ "Agents" ], "summary": "Create agent", "description": "Creates a new agent. If `url` is provided, a link source is created from that URL and training is queued automatically.\n\nThe agent is always created even if source setup or training fails — `id` is always returned. Check `pendingSteps` in the response to see which steps need to be retried:\n- `ADD_SOURCE` — the URL could not be added as a source. Add sources manually via the Sources API.\n- `TRAIN_AGENT` — training could not be started. Trigger it manually via `POST /agents/{agentId}/train`.\n\nWhen `pendingSteps` is absent, all steps succeeded.\n\nSubject to plan agent limits — returns `AGENT_LIMIT_REACHED` (403) when the account has reached its maximum number of agents.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentBody" } } } }, "responses": { "201": { "description": "Agent created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreatedResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}": { "get": { "operationId": "getAgent", "x-mcp": { "tool": "chatbase_get_agent", "scopes": [ "agents:read" ], "annotations": { "readOnly": true, "idempotent": true } }, "tags": [ "Agents" ], "summary": "Get agent", "description": "Returns a single agent by ID.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "Agent details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } }, "put": { "operationId": "updateAgent", "x-mcp": { "tool": "chatbase_update_agent", "scopes": [ "agents:write" ], "annotations": { "idempotent": true } }, "tags": [ "Agents" ], "summary": "Update agent", "description": "Partially updates an agent. Only provided fields are changed.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentBody" } } } }, "responses": { "200": { "description": "Agent updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } }, "delete": { "operationId": "deleteAgent", "x-mcp": { "tool": "chatbase_delete_agent", "scopes": [ "agents:delete" ], "annotations": { "destructive": true } }, "tags": [ "Agents" ], "summary": "Delete agent", "description": "Permanently deletes an agent and all its sources. Also disconnects any active integrations (Slack, WhatsApp, etc.). This action is irreversible.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "Agent deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/styles": { "put": { "operationId": "updateAgentStyles", "tags": [ "Agents" ], "summary": "Update agent styles", "description": "Updates the visual styles for an agent.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentStylesBody" } } } }, "responses": { "200": { "description": "Styles updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/auto-retrain": { "put": { "operationId": "updateAgentAutoRetrain", "x-mcp": { "tool": "chatbase_update_agent_auto_retrain", "scopes": [ "sources:write" ], "annotations": { "idempotent": true } }, "tags": [ "Agents" ], "summary": "Toggle auto-retrain", "description": "Enables or disables automatic retraining. When enabled, the agent retrains every 7 days to reflect any source changes.\n\nRequirements:\n- The agent must have been trained at least once — returns `AGENT_NOT_TRAINED` (409) otherwise.\n- Requires the Basic plan or higher — returns `PLAN_FEATURE_NOT_AVAILABLE` (403) on unsupported plans.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentAutoRetrainBody" } } } }, "responses": { "200": { "description": "Auto-retrain setting updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "409": { "description": "Auto-retrain requires the agent to have completed at least one training run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_TRAINED", "message": "Agent has not been trained yet. Train the agent before enabling auto-retrain." } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/clone": { "post": { "operationId": "cloneAgent", "x-mcp": { "tool": "chatbase_clone_agent", "scopes": [ "agents:write" ], "annotations": {} }, "tags": [ "Agents" ], "summary": "Clone agent", "description": "Creates a full deep-clone of an agent, including all its sources (excluding Notion). Returns the new agent ID.\n\nSame response shape as Create Agent — `pendingSteps` indicates if training could not start automatically. The clone is a new, independent agent; changes to the original do not affect it.\n\nSubject to plan agent limits — returns `AGENT_LIMIT_REACHED` (403) when the account has reached its maximum number of agents.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "responses": { "201": { "description": "Agent cloned — returns the new agent ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreatedResponse" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/train": { "post": { "operationId": "trainAgent", "tags": [ "Agents" ], "summary": "Train agent (deprecated)", "deprecated": true, "description": "**Deprecated.** Sources train as soon as they are created, updated or deleted, so changes take effect immediately and there is nothing to trigger. The call does nothing and always succeeds. Poll `GET /agents/{agentId}/sources/{sourceId}` and read `status` to follow a source, or `GET /agents/{agentId}` for the agent-level `status`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "Nothing to do — sources already train on write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeprecatedEndpointResponse" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } } } } }, "/agents/{agentId}/chat": { "post": { "operationId": "chatWithAgent", "x-mcp": { "tool": "chatbase_chat", "scopes": [ "chatlogs:write" ], "annotations": { "openWorld": true } }, "tags": [ "Agents" ], "summary": "Chat with an agent", "description": "Send a message to an agent and receive a response. Supports streaming responses when `stream: true` is set in the request body.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/StreamFinishMetadata" } }, "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatResponse" } }, "required": [ "data" ] } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "402": { "description": "The account's message credit balance is zero. Upgrade the plan or wait for credits to reset at the next billing cycle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "CHAT_CREDITS_EXHAUSTED", "message": "Message limit reached" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/conversations/{conversationId}/retry": { "post": { "operationId": "retryMessage", "tags": [ "Agents" ], "summary": "Retry a message", "description": "Retry generating an assistant response for a given message. Truncates the conversation at the target message, then re-sends the preceding user message through the chat service.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The conversation ID", "example": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }, "required": true, "description": "The conversation ID", "name": "conversationId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Streaming text response" } }, "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChatResponse" } }, "required": [ "data" ] } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "402": { "description": "The account's message credit balance is zero. Upgrade the plan or wait for credits to reset at the next billing cycle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "CHAT_CREDITS_EXHAUSTED", "message": "Message limit reached" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "The provided `messageId` does not exist in the conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "CHAT_RETRY_MESSAGE_NOT_FOUND", "message": "Message not found in conversation" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/voice/sessions": { "post": { "operationId": "createVoiceSession", "tags": [ "Agents" ], "summary": "Start a voice session", "description": "Create a real-time voice session for an agent. Pass the response `data` to the Chatbase Voice SDK (`@chatbase-co/voice-sdk`) in your client: the SDK connects, publishes the microphone, and the agent joins automatically. Requires a plan with voice mode enabled; voice minutes consume message credits. Send `{}` when no options are needed.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceSessionRequest" } } } }, "responses": { "200": { "description": "Voice session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VoiceSessionResponse" } }, "required": [ "data" ] } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/conversations": { "get": { "operationId": "listConversations", "tags": [ "Conversations" ], "summary": "List conversations", "description": "List conversations created through the API for an agent, ordered by createdAt date. Conversations from other sources (widget, WhatsApp, etc.) are not included; use Search conversations or Export conversations for those. Supports cursor-based pagination. Pass `startDate` and/or `endDate` to restrict the results to a createdAt window.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response to fetch the next page", "example": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items per page (1 to 100, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1 to 100, default 20)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Only return conversations created at or after this point. Accepts a calendar date (`YYYY-MM-DD`, interpreted as the start of that day in UTC) or an ISO 8601 date-time.", "example": "2024-01-01" }, "required": false, "description": "Only return conversations created at or after this point. Accepts a calendar date (`YYYY-MM-DD`, interpreted as the start of that day in UTC) or an ISO 8601 date-time.", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "description": "Only return conversations created at or before this point. Accepts a calendar date (`YYYY-MM-DD`, interpreted as the *end* of that day in UTC, so the day itself is included) or an ISO 8601 date-time.", "example": "2024-01-31" }, "required": false, "description": "Only return conversations created at or before this point. Accepts a calendar date (`YYYY-MM-DD`, interpreted as the *end* of that day in UTC, so the day itself is included) or an ISO 8601 date-time.", "name": "endDate", "in": "query" } ], "responses": { "200": { "description": "Paginated list of conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConversationsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_INVALID_BODY": { "summary": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "value": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } }, "VALIDATION_INVALID_DATE_RANGE": { "summary": "The requested `createdAt` window is inverted. An inverted window can never match a row, so it is rejected rather than silently returning an empty page.", "value": { "error": { "code": "VALIDATION_INVALID_DATE_RANGE", "message": "startDate must not be after endDate" } } } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/conversations/export": { "get": { "operationId": "exportConversations", "x-mcp": { "tool": "chatbase_export_conversations", "scopes": [ "chatlogs:export" ], "annotations": { "readOnly": true, "idempotent": true }, "fields": [ "id", "title", "source", "embedOrigin", "status", "userId", "createdAt", "updatedAt", "parentConversationId", "parentSummary", "messages" ], "maxItems": 20 }, "tags": [ "Conversations" ], "summary": "Export conversations", "description": "Export all conversations with full message history for an agent. Includes conversations from all sources. Tool results are sanitized to remove internal data. Supports cursor-based pagination. Pass `conversationId` to fetch a single conversation from any source (widget, API, WhatsApp, etc.). Pass `include=summary` to omit message bodies for a cheaper triage pass, `source` to restrict to one or more conversation sources, and `startDate` / `endDate` to restrict to a createdAt window.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response to fetch the next page", "example": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20, "description": "Number of items per page (1–20, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1–20, default 20)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Only return conversations created at or after this point. Accepts a calendar date (`YYYY-MM-DD`, interpreted as the start of that day in UTC) or an ISO 8601 date-time.", "example": "2024-01-01" }, "required": false, "description": "Only return conversations created at or after this point. Accepts a calendar date (`YYYY-MM-DD`, interpreted as the start of that day in UTC) or an ISO 8601 date-time.", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "description": "Only return conversations created at or before this point. Accepts a calendar date (`YYYY-MM-DD`, interpreted as the *end* of that day in UTC, so the day itself is included) or an ISO 8601 date-time.", "example": "2024-01-31" }, "required": false, "description": "Only return conversations created at or before this point. Accepts a calendar date (`YYYY-MM-DD`, interpreted as the *end* of that day in UTC, so the day itself is included) or an ISO 8601 date-time.", "name": "endDate", "in": "query" }, { "schema": { "type": "string", "description": "Return only the conversation with this ID. Use this to fetch a single conversation from any source (widget, API, WhatsApp, etc.)." }, "required": false, "description": "Return only the conversation with this ID. Use this to fetch a single conversation from any source (widget, API, WhatsApp, etc.).", "name": "conversationId", "in": "query" }, { "schema": { "type": "string", "enum": [ "summary", "messages" ], "default": "messages", "description": "Whether to include message bodies. `summary` omits them and skips reading them from the database — use it to triage a page cheaply, then re-request a specific conversation with `conversationId`. Defaults to `messages`.", "example": "summary" }, "required": false, "description": "Whether to include message bodies. `summary` omits them and skips reading them from the database — use it to triage a page cheaply, then re-request a specific conversation with `conversationId`. Defaults to `messages`.", "name": "include", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated conversation sources to include, e.g. `API,WhatsApp`. Omit for all sources.", "example": "Widget or Iframe" }, "required": false, "description": "Comma-separated conversation sources to include, e.g. `API,WhatsApp`. Omit for all sources.", "name": "source", "in": "query" } ], "responses": { "200": { "description": "Paginated list of conversations with full message history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportConversationsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_INVALID_BODY": { "summary": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "value": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } }, "VALIDATION_INVALID_DATE_RANGE": { "summary": "The requested `createdAt` window is inverted. An inverted window can never match a row, so it is rejected rather than silently returning an empty page.", "value": { "error": { "code": "VALIDATION_INVALID_DATE_RANGE", "message": "startDate must not be after endDate" } } } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/conversations/search": { "get": { "operationId": "searchConversations", "x-mcp": { "tool": "chatbase_search_conversations", "scopes": [ "chatlogs:export" ], "annotations": { "readOnly": true, "idempotent": true }, "maxItems": 25 }, "tags": [ "Conversations" ], "summary": "Search conversations", "description": "Search an agent's conversations by text, filters, or both. With `query`, results are ranked and carry a highlighted snippet; without it, most recently active first. Filters combine with AND; comma-separated values within a filter with OR. Covers conversations created since the 1st of the month 12 months ago (UTC), activity-date filters included. Results lag new messages by a few seconds. A page can hold fewer than `limit` items, even none, while `hasMore` is true; keep paging. Read messages via export with `conversationId`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "description": "Created at or after this point (`YYYY-MM-DD` or ISO 8601). Must be inside the searchable window." }, "required": false, "description": "Created at or after this point (`YYYY-MM-DD` or ISO 8601). Must be inside the searchable window.", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "description": "Created at or before this point (`YYYY-MM-DD`, inclusive, or ISO 8601)." }, "required": false, "description": "Created at or before this point (`YYYY-MM-DD`, inclusive, or ISO 8601).", "name": "endDate", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "Free-text search over messages and titles.", "example": "refund" }, "required": false, "description": "Free-text search over messages and titles.", "name": "query", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated sources, e.g. `API,WhatsApp`.", "example": "Widget or Iframe" }, "required": false, "description": "Comma-separated sources, e.g. `API,WhatsApp`.", "name": "source", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated: `positive`, `neutral`, `negative`, or `unspecified` for none.", "example": "negative" }, "required": false, "description": "Comma-separated: `positive`, `neutral`, `negative`, or `unspecified` for none.", "name": "sentiment", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated topic names, or `unspecified` for none.", "example": "billing" }, "required": false, "description": "Comma-separated topic names, or `unspecified` for none.", "name": "topic", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated user IDs." }, "required": false, "description": "Comma-separated user IDs.", "name": "userId", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated: `ongoing`, `ended`, `taken_over`, `paused`.", "example": "taken_over" }, "required": false, "description": "Comma-separated: `ongoing`, `ended`, `taken_over`, `paused`.", "name": "activityState", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated message ratings: `positive`, `negative`.", "example": "negative" }, "required": false, "description": "Comma-separated message ratings: `positive`, `negative`.", "name": "feedback", "in": "query" }, { "schema": { "type": "string", "enum": [ "true" ], "description": "`true`: only conversations escalated to a human (ticket or live-chat handoff).", "example": "true" }, "required": false, "description": "`true`: only conversations escalated to a human (ticket or live-chat handoff).", "name": "escalated", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated action types that ran, e.g. `collect-leads`." }, "required": false, "description": "Comma-separated action types that ran, e.g. `collect-leads`.", "name": "actionType", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated tool names that were called." }, "required": false, "description": "Comma-separated tool names that were called.", "name": "tool", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated tool result statuses, e.g. `error`. Scoped to `tool` when set.", "example": "error" }, "required": false, "description": "Comma-separated tool result statuses, e.g. `error`. Scoped to `tool` when set.", "name": "toolOutcome", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated procedure names that ran." }, "required": false, "description": "Comma-separated procedure names that ran.", "name": "procedure", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated procedure run statuses. Scoped to `procedure` when set.", "example": "completed" }, "required": false, "description": "Comma-separated procedure run statuses. Scoped to `procedure` when set.", "name": "procedureOutcome", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Whether a voice session took place." }, "required": false, "description": "Whether a voice session took place.", "name": "hasVoice", "in": "query" }, { "schema": { "type": "string", "description": "Last active at or after this point (`YYYY-MM-DD` or ISO 8601)." }, "required": false, "description": "Last active at or after this point (`YYYY-MM-DD` or ISO 8601).", "name": "updatedAfter", "in": "query" }, { "schema": { "type": "string", "description": "Last active at or before this point (`YYYY-MM-DD`, inclusive, or ISO 8601)." }, "required": false, "description": "Last active at or before this point (`YYYY-MM-DD`, inclusive, or ISO 8601).", "name": "updatedBefore", "in": "query" }, { "schema": { "type": "string", "maxLength": 2048, "description": "`pagination.cursor` from the previous page. Keep the other parameters unchanged." }, "required": false, "description": "`pagination.cursor` from the previous page. Keep the other parameters unchanged.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 25, "description": "Items per page (1 to 25, default 25)", "example": 25 }, "required": false, "description": "Items per page (1 to 25, default 25)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Matching conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchConversationsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_INVALID_BODY": { "summary": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "value": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } }, "VALIDATION_INVALID_DATE_RANGE": { "summary": "The requested `createdAt` window is inverted. An inverted window can never match a row, so it is rejected rather than silently returning an empty page.", "value": { "error": { "code": "VALIDATION_INVALID_DATE_RANGE", "message": "startDate must not be after endDate" } } }, "VALIDATION_INVALID_CURSOR": { "summary": "The `cursor` could not be decoded. Pass the exact `pagination.cursor` value from a previous response, without modification.", "value": { "error": { "code": "VALIDATION_INVALID_CURSOR", "message": "Invalid pagination cursor" } } }, "VALIDATION_CURSOR_QUERY_MISMATCH": { "summary": "The cursor was issued for a different `query` or filter set. Keep every search parameter except `cursor` and `limit` constant across a cursor walk, or drop the cursor to restart from the first page.", "value": { "error": { "code": "VALIDATION_CURSOR_QUERY_MISMATCH", "message": "Cursor does not match the requested search" } } }, "VALIDATION_SEARCH_WINDOW_EXCEEDED": { "summary": "Conversation search covers conversations created since the first day of the month twelve months ago (UTC). `startDate`, `endDate` and `updatedBefore` must fall inside that window; use the export endpoint for older conversations.", "value": { "error": { "code": "VALIDATION_SEARCH_WINDOW_EXCEEDED", "message": "The requested dates are before the searchable window" } } } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CONVERSATION_SEARCH_UNAVAILABLE": { "summary": "HIPAA-enabled accounts and agents configured to redact conversation data cannot run a free-text `query`. Filters alone are still allowed.", "value": { "error": { "code": "CONVERSATION_SEARCH_UNAVAILABLE", "message": "Conversation search is not available for this agent" } } }, "AUTH_INSUFFICIENT_PERMISSIONS": { "summary": "The API key does not have the required permissions for this operation. Ensure the key's account has the appropriate plan and role.", "value": { "error": { "code": "AUTH_INSUFFICIENT_PERMISSIONS", "message": "You don't have permission to perform this action" } } }, "SUBSCRIPTION_API_RESTRICTED_PLAN": { "summary": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "value": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "SERVICE_UNDER_MAINTENANCE": { "summary": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "value": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } }, "CONVERSATION_SEARCH_BUSY": { "summary": "The search index timed out or is overloaded. This is transient; retry after a short delay.", "value": { "error": { "code": "CONVERSATION_SEARCH_BUSY", "message": "Conversation search is temporarily unavailable, please retry" } } } } } } } } } }, "/agents/{agentId}/conversations/{conversationId}": { "get": { "operationId": "getConversation", "tags": [ "Conversations" ], "summary": "Get a conversation", "description": "Get conversation metadata and its most recent messages. The pagination cursor can be used with the list messages endpoint to fetch older messages. Only returns conversations created through the API. To fetch a conversation from any source (widget, WhatsApp, etc.), use GET /agents/{agentId}/conversations/export?conversationId={conversationId} instead.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The conversation ID", "example": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }, "required": true, "description": "The conversation ID", "name": "conversationId", "in": "path" } ], "responses": { "200": { "description": "Conversation metadata with recent messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConversationResponse" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No resource matches the provided ID, or it has been deleted. Verify the resource ID in the request path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested item could not be found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } }, "patch": { "operationId": "updateConversation", "x-mcp": { "tool": "chatbase_update_conversation", "scopes": [ "chatlogs:write" ], "annotations": { "idempotent": true } }, "tags": [ "Conversations" ], "summary": "Update conversation status", "description": "Update the activity state of a conversation.\n\n- `ongoing` — resumes a paused or ended conversation. Only API-source conversations can be resumed from ended.\n- `paused` — pauses an ongoing conversation (stops AI replies but still records messages).\n- `ended` — ends the conversation.\n\nConversation-based billing accounts cannot resume ended conversations.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The conversation ID", "example": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }, "required": true, "description": "The conversation ID", "name": "conversationId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversationRequest" } } } }, "responses": { "200": { "description": "Conversation updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversationResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "409": { "description": "Another actor (e.g. an operator taking over) changed the conversation between read and write. Nothing was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "CONVERSATION_STATE_CHANGED", "message": "The conversation changed state during the update, please retry" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } }, "delete": { "operationId": "deleteConversation", "x-mcp": { "tool": "chatbase_delete_conversation", "scopes": [ "chatlogs:delete" ], "annotations": { "destructive": true } }, "tags": [ "Conversations" ], "summary": "Delete conversation", "description": "Deletes a conversation from any source (API, widget, WhatsApp, etc.). It no longer appears in chat logs or in API responses.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The conversation ID", "example": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }, "required": true, "description": "The conversation ID", "name": "conversationId", "in": "path" } ], "responses": { "200": { "description": "Conversation deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "409": { "description": "HIPAA accounts can delete a conversation only after its HIPAA processing finishes. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "CONVERSATION_AWAITING_HIPAA_PROCESSING", "message": "The conversation is still awaiting HIPAA processing and cannot be deleted yet" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/conversations/{conversationId}/messages": { "get": { "operationId": "listConversationMessages", "tags": [ "Conversations" ], "summary": "List conversation messages", "description": "List all messages in a conversation with cursor-based pagination. Messages are returned in chronological order within each page, paginating backward from newest. The cursor from the get-conversation endpoint works here.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The conversation ID", "example": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }, "required": true, "description": "The conversation ID", "name": "conversationId", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response to fetch the next page", "example": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items per page (1 to 100, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1 to 100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Paginated list of messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMessagesResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No resource matches the provided ID, or it has been deleted. Verify the resource ID in the request path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RESOURCE_NOT_FOUND", "message": "The requested item could not be found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/users/{userId}/conversations": { "get": { "operationId": "listUserConversations", "tags": [ "Conversations" ], "summary": "List conversations for a user", "description": "List conversations created through the API for a specific user under an agent, ordered by last activity. Conversations from other sources (widget, WhatsApp, etc.) are not included; use Search conversations with `userId` to find them, and Export conversations to read their messages. Supports cursor-based pagination.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9._-]+$", "description": "The user ID (URL-safe characters only: letters, digits, hyphens, underscores, dots)", "example": "user_abc123" }, "required": true, "description": "The user ID (URL-safe characters only: letters, digits, hyphens, underscores, dots)", "name": "userId", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response to fetch the next page", "example": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items per page (1 to 100, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1 to 100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Paginated list of user conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListUserConversationsResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } }, "delete": { "operationId": "deleteUserConversations", "tags": [ "Conversations" ], "summary": "Delete all conversations for a user", "description": "Deletes every conversation of a user under an agent, from any source (API, widget, WhatsApp, etc.). They no longer appear in chat logs or in API responses. Deleting a contact does not delete their conversations; call this endpoint as well.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The user ID, URL-encoded (for example `jane%40example.com` for `jane@example.com`). For widget conversations of identified users, this is the contact's external ID.", "example": "user_abc123" }, "required": true, "description": "The user ID, URL-encoded (for example `jane%40example.com` for `jane@example.com`). For widget conversations of identified users, this is the contact's external ID.", "name": "userId", "in": "path" } ], "responses": { "200": { "description": "Conversations deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteUserConversationsResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback": { "patch": { "operationId": "updateMessageFeedback", "tags": [ "Conversations" ], "summary": "Update message feedback", "description": "Set or clear feedback on an assistant message. Use \"positive\" or \"negative\" to set feedback, or null to remove existing feedback.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The conversation ID", "example": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }, "required": true, "description": "The conversation ID", "name": "conversationId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The message ID" }, "required": true, "description": "The message ID", "name": "messageId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMessageFeedbackRequest" } } } }, "responses": { "200": { "description": "Updated message with feedback", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMessageFeedbackResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No message matches the provided ID in this conversation. Verify the message ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RESOURCE_MESSAGE_NOT_FOUND", "message": "The specified message could not be found in this conversation" } } } } }, "422": { "description": "The specified message is not an assistant message. Metadata updates are only supported on assistant text messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RESOURCE_MESSAGE_NOT_ASSISTANT", "message": "Only assistant messages support metadata updates" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/conversations/{conversationId}/tool-result": { "post": { "operationId": "submitToolResult", "tags": [ "Agents" ], "summary": "Submit a tool result", "description": "Submit the result of a client-side tool call. Use the toolCallId from the tool-call part in the chat response to identify the tool call.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The conversation ID", "example": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }, "required": true, "description": "The conversation ID", "name": "conversationId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitToolResultRequest" } } } }, "responses": { "200": { "description": "Tool result submitted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitToolResultResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No pending tool call matches the provided `toolCallId`. It may have expired or already been resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RESOURCE_TOOL_CALL_NOT_FOUND", "message": "Tool call not found or expired" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/sources/summary": { "get": { "operationId": "getSourcesSummary", "x-mcp": { "tool": "chatbase_get_sources_summary", "scopes": [ "sources:read" ], "annotations": { "readOnly": true, "idempotent": true } }, "tags": [ "Sources" ], "summary": "Get sources summary", "description": "Returns aggregated counts and sizes for each source type, plus a flag if the chatbot knowledge base requires a retrain to reflect any changes", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "Sources summary by type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourcesSummaryResponse" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/sources": { "get": { "operationId": "listSources", "x-mcp": { "tool": "chatbase_list_sources", "scopes": [ "sources:read" ], "annotations": { "readOnly": true, "idempotent": true }, "maxItems": 50 }, "tags": [ "Sources" ], "summary": "List sources", "description": "Returns a paginated list of sources for an agent. Ticket sources are excluded. For link sources only individual or sitemap/crawl parent links are returned with aggregated children metadata.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response to fetch the next page", "example": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items per page (1 to 100, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1 to 100, default 20)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated source types to filter by. Allowed values: link, file, qna, notionPage, text", "example": "file,qna" }, "required": false, "description": "Comma-separated source types to filter by. Allowed values: link, file, qna, notionPage, text", "name": "type", "in": "query" }, { "schema": { "type": "string", "description": "Partial (case-insensitive) name match", "example": "handbook" }, "required": false, "description": "Partial (case-insensitive) name match", "name": "name", "in": "query" } ], "responses": { "200": { "description": "Paginated list of sources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSourcesResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } }, "post": { "operationId": "createSource", "x-mcp": { "tool": "chatbase_create_source", "scopes": [ "sources:write" ], "annotations": {} }, "tags": [ "Sources" ], "summary": "Create source", "description": "Creates a new source. Accepts text, qna, and link source types. File sources require a dedicated endpoint. Ticket and Notion sources are not accepted. The source starts training immediately — no separate training call is needed. It is returned as `untrained` and flips to `trained` when it is live, or `failed` if training did not land; poll `GET /agents/{agentId}/sources/{sourceId}` to follow it.\n\n**Q&A request body limit:** The total request body must not exceed 4.5 MB for Q&A sources.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSourceBody" } } } }, "responses": { "201": { "description": "Source created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceListItem" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "409": { "description": "A parent link with this URL and link type already exists for this agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_DUPLICATE", "message": "A source with this URL and type already exists" } } } } }, "422": { "description": "Adding or updating this source would exceed the storage limit for your plan. Remove existing sources, upgrade your plan or add extra storage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_SIZE_LIMIT_EXCEEDED", "message": "Chatbot storage limit exceeded" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/sources/{sourceId}": { "get": { "operationId": "getSource", "x-mcp": { "tool": "chatbase_get_source", "scopes": [ "sources:read" ], "annotations": { "readOnly": true, "idempotent": true } }, "tags": [ "Sources" ], "summary": "Get source", "description": "Returns a single source by ID.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The source ID", "example": "a63a69a5-e7a9-4757-b73b-2041854d435d" }, "required": true, "description": "The source ID", "name": "sourceId", "in": "path" } ], "responses": { "200": { "description": "Source details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceListItem" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } }, "delete": { "operationId": "deleteSource", "x-mcp": { "tool": "chatbase_delete_source", "scopes": [ "sources:delete" ], "annotations": { "destructive": true } }, "tags": [ "Sources" ], "summary": "Delete source", "description": "Deletes a source. Its knowledge is removed from the agent immediately; the response carries the final state (`deleted`, or `toBeDeleted` while the purge finishes).", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The source ID", "example": "a63a69a5-e7a9-4757-b73b-2041854d435d" }, "required": true, "description": "The source ID", "name": "sourceId", "in": "path" } ], "responses": { "200": { "description": "Source in its final state after marking for deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedSourceListItem" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "409": { "description": "This source is already marked for deletion. Call the restore endpoint to undo the pending deletion first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_ALREADY_PENDING_DELETION", "message": "Source is already pending deletion" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } }, "put": { "operationId": "updateSource", "x-mcp": { "tool": "chatbase_update_source", "scopes": [ "sources:write" ], "annotations": { "idempotent": true } }, "tags": [ "Sources" ], "summary": "Update source", "description": "Updates an existing source. Accepts text, qna, and link sources. File sources require a dedicated endpoint. A content change retrains the source immediately (status `updated` until it is live again). Link URL is immutable — to change it, delete and recreate the source. Ticket and Notion sources are not accepted.\n\n**Q&A request body limit:** The total request body must not exceed 4.5 MB for Q&A sources.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The source ID", "example": "a63a69a5-e7a9-4757-b73b-2041854d435d" }, "required": true, "description": "The source ID", "name": "sourceId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSourceBody" } } } }, "responses": { "200": { "description": "Updated source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceListItem" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "409": { "description": "Restore the source before making changes to it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_PENDING_DELETION", "message": "Source is pending deletion and cannot be edited" } } } } }, "422": { "description": "Adding or updating this source would exceed the storage limit for your plan. Remove existing sources, upgrade your plan or add extra storage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_SIZE_LIMIT_EXCEEDED", "message": "Chatbot storage limit exceeded" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/sources/{sourceId}/restore": { "post": { "operationId": "restoreSource", "tags": [ "Sources" ], "summary": "Restore source (deprecated)", "deprecated": true, "description": "**Deprecated.** A delete takes effect immediately — the knowledge is purged right away, so there is no pending state to restore from. The call does nothing and always succeeds. Re-create the source instead.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "The source ID", "example": "a63a69a5-e7a9-4757-b73b-2041854d435d" }, "required": true, "description": "The source ID", "name": "sourceId", "in": "path" } ], "responses": { "200": { "description": "Nothing to do — deletes are final", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeprecatedEndpointResponse" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } } } } }, "/agents/{agentId}/whatsapp/templates": { "get": { "operationId": "listWhatsAppTemplates", "tags": [ "WhatsApp" ], "summary": "List WhatsApp templates", "description": "Lists the approved WhatsApp templates available to the agent, across all of its connected WhatsApp Business Accounts. Each template's `variables` object is the shape a send request must provide. A template can only be sent from a number on its own Business Account, so pair its `wabaId` with a matching entry in `senders` to pick the `from` value. Check `complete` before treating the list as exhaustive: it is `false` when one of the agent’s Business Accounts could not be read.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "The available templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWhatsAppTemplatesResponse" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "The agent exists but has no WhatsApp phone number connected. Connect a number from the deploy page before calling WhatsApp endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "WHATSAPP_NOT_CONNECTED", "message": "WhatsApp is not connected for this agent" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } } } } }, "/agents/{agentId}/whatsapp/messages/template": { "post": { "operationId": "sendWhatsAppTemplateMessage", "tags": [ "WhatsApp" ], "summary": "Send a WhatsApp template message", "description": "Sends an approved WhatsApp template to a recipient from one of the agent's connected phone numbers. Recipients are identified by phone number only — no user ID is required. A Chatbase user is resolved or created from the `to` number automatically, and their reply flows through the agent's regular WhatsApp pipeline. The message is also appended to that conversation, unless a human has taken it over or it has ended — see `conversationId` in the response.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendWhatsAppTemplateBody" } } } }, "responses": { "201": { "description": "The message was accepted by WhatsApp", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendWhatsAppTemplateResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PHONE_NUMBER_REQUIRED": { "summary": "The agent has more than one connected WhatsApp number, so `from` must be provided to pick the sender.", "value": { "error": { "code": "PHONE_NUMBER_REQUIRED", "message": "This agent has multiple WhatsApp phone numbers; specify a `from` number" } } }, "TEMPLATE_LANGUAGE_REQUIRED": { "summary": "The template name has more than one approved language variant. Pass `template.language` to choose one. Variants that are not approved are ignored, so this is only returned when the choice is genuinely ambiguous.", "value": { "error": { "code": "TEMPLATE_LANGUAGE_REQUIRED", "message": "Multiple languages exist for this template; specify a language" } } } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "The agent exists but has no WhatsApp phone number connected. Connect a number from the deploy page before calling WhatsApp endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "WHATSAPP_NOT_CONNECTED", "message": "WhatsApp is not connected for this agent" } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "PHONE_NUMBER_NOT_FOUND": { "summary": "No WhatsApp number connected to this agent matches the provided `from` number.", "value": { "error": { "code": "PHONE_NUMBER_NOT_FOUND", "message": "WhatsApp phone number not found for this agent" } } }, "TEMPLATE_NOT_FOUND": { "summary": "No template with the given name (and language, if provided) exists on the WhatsApp Business Account of the sending phone number. When the agent has numbers on more than one Business Account, check that the `from` number’s `wabaId` matches the template’s `wabaId` from the list endpoint.", "value": { "error": { "code": "TEMPLATE_NOT_FOUND", "message": "WhatsApp template not found" } } } } } } }, "409": { "description": "Cannot send in the current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "TEMPLATE_NOT_APPROVED": { "summary": "The template exists but has no approved variant to send. The `details.status` field carries the Meta review status, broken down per language when the name has several unapproved variants.", "value": { "error": { "code": "TEMPLATE_NOT_APPROVED", "message": "WhatsApp template is not approved" } } }, "SEND_BLOCKED": { "summary": "Meta has blocked business-initiated conversations for this WhatsApp Business Account — commonly a billing or payment-method problem, or an account restriction. The `details.reason` field carries Meta's explanation. Resolve it in WhatsApp Manager; sends resume within a minute of the account being healthy again.", "value": { "error": { "code": "SEND_BLOCKED", "message": "This WhatsApp Business Account is not allowed to start new conversations" } } } } } } }, "422": { "description": "Unprocessable message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "MISSING_TEMPLATE_VARIABLES": { "summary": "The template declares variables that were not provided. The `details.missing` field lists them as `component[key]`, e.g. `body[2]`.", "value": { "error": { "code": "MISSING_TEMPLATE_VARIABLES", "message": "Missing values for template variables" } } }, "INVALID_TEMPLATE_VARIABLES": { "summary": "WhatsApp refuses a parameter that is empty, or that contains a line break, a tab, or more than four consecutive spaces. It reports all of these as the same opaque send failure, so they are rejected here instead. The `details.invalid` field names each offending slot and why, as `body[1] (contains a line break)`.", "value": { "error": { "code": "INVALID_TEMPLATE_VARIABLES", "message": "One or more template variable values are not accepted by WhatsApp" } } }, "TEMPLATE_BUTTONS_UNSUPPORTED": { "summary": "The template has a button that takes a parameter — a dynamic URL, a copy-code, or a one-time-password button — which this endpoint cannot send. WhatsApp would reject the message, so it is refused up front rather than attempted. The `details.buttons` field lists the button types. Campaigns cannot send these either — no Chatbase surface builds button parameters today — so edit the template in WhatsApp Manager to use a static button, or send a variant that has none.", "value": { "error": { "code": "TEMPLATE_BUTTONS_UNSUPPORTED", "message": "Template buttons are not supported by this endpoint" } } }, "TEMPLATE_PARAMS_REJECTED": { "summary": "The WhatsApp API rejected the send because the provided parameters do not match the approved template (wrong count, format, or content).", "value": { "error": { "code": "TEMPLATE_PARAMS_REJECTED", "message": "Meta rejected the template parameters" } } }, "RECIPIENT_INVALID": { "summary": "The `to` phone number is not a valid international phone number — it is parsed and validated against its country, so an unassignable number (e.g. a `555` US area code) is rejected. Use digits only with country code, e.g. 14155552671.", "value": { "error": { "code": "RECIPIENT_INVALID", "message": "Recipient phone number is invalid" } } }, "RECIPIENT_NOT_REACHABLE": { "summary": "The WhatsApp API reported the recipient as undeliverable — the number may not be on WhatsApp or has blocked business messages.", "value": { "error": { "code": "RECIPIENT_NOT_REACHABLE", "message": "Recipient cannot receive WhatsApp messages" } } } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "502": { "description": "Upstream WhatsApp API failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "WHATSAPP_SEND_FAILED": { "summary": "The WhatsApp API returned an error that does not map to a more specific code.", "value": { "error": { "code": "WHATSAPP_SEND_FAILED", "message": "WhatsApp API rejected the message" } } }, "MEDIA_UPLOAD_FAILED": { "summary": "The template has a media header and uploading its media to the WhatsApp API failed.", "value": { "error": { "code": "MEDIA_UPLOAD_FAILED", "message": "Failed to upload the template header media to WhatsApp" } } } } } } } } } }, "/agents/{agentId}/helpdesk/ticket-statuses": { "get": { "operationId": "listTicketStatuses", "x-mcp": { "tool": "chatbase_list_ticket_statuses", "scopes": [ "helpdesk_tickets:read" ], "annotations": { "readOnly": true, "idempotent": true } }, "tags": [ "Helpdesk" ], "summary": "List ticket statuses", "description": "Returns the active (non-archived) ticket statuses configured for an agent, ordered by category then position. Each category has exactly one default status.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "List of ticket statuses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketStatusList" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/helpdesk/teams": { "get": { "operationId": "listHelpdeskTeams", "x-mcp": { "tool": "chatbase_list_helpdesk_teams", "scopes": [ "helpdesk_tickets:read" ], "annotations": { "readOnly": true, "idempotent": true } }, "tags": [ "Helpdesk" ], "summary": "List teams", "description": "Returns the teams configured for an agent, ordered by creation date. Exactly one team is marked as the default for the agent.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "responses": { "200": { "description": "List of teams", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamListResponse" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/helpdesk/attendance": { "get": { "operationId": "listAttendanceRows", "x-mcp": { "tool": "chatbase_list_attendance_rows", "scopes": [ "analytics:read" ], "annotations": { "readOnly": true, "idempotent": true }, "fields": [ "date", "operator", "shiftNumber", "shiftCount", "shiftName", "scheduledStart", "scheduledEnd", "loggedStart", "loggedEnd", "timeLoggedMinutes", "lateMinutes", "leftEarlyMinutes", "unplannedTimeOff", "plannedTimeOff", "adherencePercent" ], "maxItems": 50 }, "tags": [ "Helpdesk" ], "summary": "List attendance rows", "description": "Returns the Attendance report for each day in the range: one row per operator for each part of a shift and for time logged outside them, matching the Attendance CSV export. Days are calendar days in `timezone`. A day that has not ended yet returns what has happened so far. Pages can shift if the data changes between calls. Both reports share a limit of 30 calls per 10 seconds per account.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response to fetch the next page", "example": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Number of items per page (1 to 1000, default 100)", "example": 100 }, "required": false, "description": "Number of items per page (1 to 1000, default 100)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "First day to return (`YYYY-MM-DD`), as a calendar day in `timezone`. At most 396 days ago.", "example": "2026-10-29" }, "required": true, "description": "First day to return (`YYYY-MM-DD`), as a calendar day in `timezone`. At most 396 days ago.", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Last day to return (`YYYY-MM-DD`), inclusive. Not after today in `timezone`, and at most 31 days from `startDate` counting both.", "example": "2026-10-30" }, "required": true, "description": "Last day to return (`YYYY-MM-DD`), inclusive. Not after today in `timezone`, and at most 31 days from `startDate` counting both.", "name": "endDate", "in": "query" }, { "schema": { "type": "string", "description": "IANA time zone that decides where each day starts and ends, the same as the time zone picker on the dashboard.", "example": "Africa/Cairo" }, "required": true, "description": "IANA time zone that decides where each day starts and ends, the same as the time zone picker on the dashboard.", "name": "timezone", "in": "query" } ], "responses": { "200": { "description": "Attendance rows, by day and then by operator name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttendanceRowListResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_INVALID_BODY": { "summary": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "value": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } }, "VALIDATION_INVALID_CURSOR": { "summary": "The `cursor` could not be decoded. Pass the exact `pagination.cursor` value from a previous response, without modification.", "value": { "error": { "code": "VALIDATION_INVALID_CURSOR", "message": "Invalid pagination cursor" } } }, "VALIDATION_CURSOR_QUERY_MISMATCH": { "summary": "The cursor was issued for a different `query` or filter set. Keep every search parameter except `cursor` and `limit` constant across a cursor walk, or drop the cursor to restart from the first page.", "value": { "error": { "code": "VALIDATION_CURSOR_QUERY_MISMATCH", "message": "Cursor does not match the requested search" } } } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "HELPDESK_NOT_ENABLED": { "summary": "The agent exists but help desk is not activated for it. Enable help desk before calling its endpoints.", "value": { "error": { "code": "HELPDESK_NOT_ENABLED", "message": "Help desk is not enabled for this agent" } } }, "AUTH_INSUFFICIENT_PERMISSIONS": { "summary": "The API key does not have the required permissions for this operation. Ensure the key's account has the appropriate plan and role.", "value": { "error": { "code": "AUTH_INSUFFICIENT_PERMISSIONS", "message": "You don't have permission to perform this action" } } }, "SUBSCRIPTION_API_RESTRICTED_PLAN": { "summary": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "value": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/helpdesk/activity": { "get": { "operationId": "listActivitySegments", "x-mcp": { "tool": "chatbase_list_activity_segments", "scopes": [ "analytics:read" ], "annotations": { "readOnly": true, "idempotent": true }, "fields": [ "operator", "kind", "ticketNumber", "startedAt", "lastSeenAt", "endedAt" ], "maxItems": 50 }, "tags": [ "Helpdesk" ], "summary": "List activity segments", "description": "Returns the stored activity segments of the agent's current Help Desk operators, unmerged and unrounded, so totals can differ slightly from the Activity export. One item per ticket, untracked or idle stretch, listed only in the range where it started. Both reports share a limit of 30 calls per 10 seconds per account.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response to fetch the next page", "example": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Number of items per page (1 to 1000, default 100)", "example": 100 }, "required": false, "description": "Number of items per page (1 to 1000, default 100)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "First day to return (`YYYY-MM-DD`), as a calendar day in `timezone`. At most 396 days ago.", "example": "2026-10-29" }, "required": true, "description": "First day to return (`YYYY-MM-DD`), as a calendar day in `timezone`. At most 396 days ago.", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "format": "date", "description": "Last day to return (`YYYY-MM-DD`), inclusive. Not after today in `timezone`, and at most 31 days from `startDate` counting both.", "example": "2026-10-30" }, "required": true, "description": "Last day to return (`YYYY-MM-DD`), inclusive. Not after today in `timezone`, and at most 31 days from `startDate` counting both.", "name": "endDate", "in": "query" }, { "schema": { "type": "string", "description": "IANA time zone that decides where each day starts and ends, the same as the time zone picker on the dashboard.", "example": "Africa/Cairo" }, "required": true, "description": "IANA time zone that decides where each day starts and ends, the same as the time zone picker on the dashboard.", "name": "timezone", "in": "query" } ], "responses": { "200": { "description": "Activity segments, by start, then segment ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivitySegmentListResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "VALIDATION_INVALID_BODY": { "summary": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "value": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } }, "VALIDATION_INVALID_CURSOR": { "summary": "The `cursor` could not be decoded. Pass the exact `pagination.cursor` value from a previous response, without modification.", "value": { "error": { "code": "VALIDATION_INVALID_CURSOR", "message": "Invalid pagination cursor" } } }, "VALIDATION_CURSOR_QUERY_MISMATCH": { "summary": "The cursor was issued for a different `query` or filter set. Keep every search parameter except `cursor` and `limit` constant across a cursor walk, or drop the cursor to restart from the first page.", "value": { "error": { "code": "VALIDATION_CURSOR_QUERY_MISMATCH", "message": "Cursor does not match the requested search" } } } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "HELPDESK_NOT_ENABLED": { "summary": "The agent exists but help desk is not activated for it. Enable help desk before calling its endpoints.", "value": { "error": { "code": "HELPDESK_NOT_ENABLED", "message": "Help desk is not enabled for this agent" } } }, "AUTH_INSUFFICIENT_PERMISSIONS": { "summary": "The API key does not have the required permissions for this operation. Ensure the key's account has the appropriate plan and role.", "value": { "error": { "code": "AUTH_INSUFFICIENT_PERMISSIONS", "message": "You don't have permission to perform this action" } } }, "SUBSCRIPTION_API_RESTRICTED_PLAN": { "summary": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "value": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/helpdesk/tickets": { "post": { "operationId": "createTicket", "x-mcp": { "tool": "chatbase_create_ticket", "scopes": [ "helpdesk_tickets:write" ], "annotations": {} }, "tags": [ "Helpdesk" ], "summary": "Create a ticket", "description": "Creates a ticket on behalf of a customer. Unless an assignee is provided, the ticket is auto-assigned via the agent's routing rules.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTicketBody" } } } }, "responses": { "201": { "description": "The created ticket", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "422": { "description": "`statusId` does not belong to a status for this agent. Discover valid ids via GET /ticket-statuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "TICKET_INVALID_STATUS", "message": "The requested status could not be applied" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } } } }, "get": { "operationId": "listTickets", "x-mcp": { "tool": "chatbase_list_tickets", "scopes": [ "helpdesk_tickets:read" ], "annotations": { "readOnly": true, "idempotent": true }, "maxItems": 25 }, "tags": [ "Helpdesk" ], "summary": "List tickets", "description": "Returns tickets for an agent, sorted by `updatedAt` descending by default. Supports filtering and cursor-based pagination. Filters combine with AND across parameters.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response to fetch the next page", "example": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items per page (1 to 100, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1 to 100, default 20)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated status categories (is-any-of). Categories: new, on_you, on_customer, on_hold, closed, cancelled.", "example": "new,on_you" }, "required": false, "description": "Comma-separated status categories (is-any-of). Categories: new, on_you, on_customer, on_hold, closed, cancelled.", "name": "status", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated channels (is-any-of).", "example": "email,api" }, "required": false, "description": "Comma-separated channels (is-any-of).", "name": "channel", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "none" ] }, { "type": "string", "format": "uuid" } ], "description": "Filter by assigned agent user id. Pass `none` for unassigned tickets." }, "required": false, "description": "Filter by assigned agent user id. Pass `none` for unassigned tickets.", "name": "assigneeId", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "none" ] }, { "type": "string", "format": "uuid" } ], "description": "Filter by team id. Pass `none` for tickets with no team." }, "required": false, "description": "Filter by team id. Pass `none` for tickets with no team.", "name": "teamId", "in": "query" }, { "schema": { "type": "string", "description": "Comma-separated priorities (is-any-of). Priorities: none, low, normal, high, urgent. Pass `none` for untriaged tickets.", "example": "high,urgent" }, "required": false, "description": "Comma-separated priorities (is-any-of). Priorities: none, low, normal, high, urgent. Pass `none` for untriaged tickets.", "name": "priority", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only tickets created at or after this ISO 8601 timestamp.", "example": "2026-07-01T00:00:00Z" }, "required": false, "description": "Only tickets created at or after this ISO 8601 timestamp.", "name": "createdAfter", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Only tickets created at or before this ISO 8601 timestamp.", "example": "2026-07-31T23:59:59Z" }, "required": false, "description": "Only tickets created at or before this ISO 8601 timestamp.", "name": "createdBefore", "in": "query" }, { "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "lastMessageAt" ], "default": "updatedAt", "description": "Sort field. `updatedAt` and `lastMessageAt` fall back to `createdAt` when unset. Sorting by a mutable field means a page window is not a snapshot. Pollers should use `sortBy=updatedAt&order=asc` with a high-water mark.", "example": "updatedAt" }, "required": false, "description": "Sort field. `updatedAt` and `lastMessageAt` fall back to `createdAt` when unset. Sorting by a mutable field means a page window is not a snapshot. Pollers should use `sortBy=updatedAt&order=asc` with a high-water mark.", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc`, newest first. A cursor is only valid for the `sortBy`/`order` it was issued with; changing either mid-walk is a 400.", "example": "desc" }, "required": false, "description": "Sort direction. Defaults to `desc`, newest first. A cursor is only valid for the `sortBy`/`order` it was issued with; changing either mid-walk is a 400.", "name": "order", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false", "description": "When `true`, the response includes `pagination.total` (costs an extra count query).", "example": "false" }, "required": false, "description": "When `true`, the response includes `pagination.total` (costs an extra count query).", "name": "includeTotal", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false", "description": "When `true`, each ticket includes `messages`: its first 25 messages, oldest first, shaped like List ticket messages.", "example": "false" }, "required": false, "description": "When `true`, each ticket includes `messages`: its first 25 messages, oldest first, shaped like List ticket messages.", "name": "includeMessages", "in": "query" }, { "schema": { "type": "string", "default": "reply,note", "description": "Message types for `messages`, as in List ticket messages. Ignored unless `includeMessages=true`.", "example": "reply,note" }, "required": false, "description": "Message types for `messages`, as in List ticket messages. Ignored unless `includeMessages=true`.", "name": "messageTypes", "in": "query" } ], "responses": { "200": { "description": "Paginated list of tickets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTicketsResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/helpdesk/tickets/search": { "post": { "operationId": "searchTickets", "x-mcp": { "tool": "chatbase_search_tickets", "scopes": [ "helpdesk_tickets:read" ], "annotations": { "readOnly": true, "idempotent": true }, "maxItems": 25 }, "tags": [ "Helpdesk" ], "summary": "Search tickets", "description": "Searches ticket messages with a free-text query and returns matching tickets ranked by relevance. Results are capped and not paginated.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchTicketsBody" } } } }, "responses": { "200": { "description": "Ranked search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchTicketsResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/agents/{agentId}/helpdesk/tickets/{ticketNumber}": { "get": { "operationId": "getTicket", "x-mcp": { "tool": "chatbase_get_ticket", "scopes": [ "helpdesk_tickets:read" ], "annotations": { "readOnly": true, "idempotent": true } }, "tags": [ "Helpdesk" ], "summary": "Get a ticket", "description": "Returns a single ticket by its per-agent ticket number.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647, "description": "The ticket number", "example": 123 }, "required": true, "description": "The ticket number", "name": "ticketNumber", "in": "path" } ], "responses": { "200": { "description": "The ticket", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "The agent could not be found (or does not belong to the authenticated account), or the ticket number does not exist for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "AGENT_NOT_FOUND": { "summary": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "value": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } }, "TICKET_NOT_FOUND": { "summary": "No ticket matches the provided ticket number for this agent. Verify the ticket number in the request path.", "value": { "error": { "code": "TICKET_NOT_FOUND", "message": "The requested ticket could not be found" } } } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } }, "patch": { "operationId": "updateTicket", "x-mcp": { "tool": "chatbase_update_ticket", "scopes": [ "helpdesk_tickets:write" ], "annotations": { "idempotent": true } }, "tags": [ "Helpdesk" ], "summary": "Update a ticket", "description": "Partially updates a ticket's status, assignee, team, or priority. Only provided fields are changed. Fields are validated together but written independently, so a 500 can leave a partial update.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647, "description": "The ticket number", "example": 123 }, "required": true, "description": "The ticket number", "name": "ticketNumber", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTicketBody" } } } }, "responses": { "200": { "description": "The updated ticket", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticket" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "The agent could not be found (or does not belong to the authenticated account), or the ticket number does not exist for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "AGENT_NOT_FOUND": { "summary": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "value": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } }, "TICKET_NOT_FOUND": { "summary": "No ticket matches the provided ticket number for this agent. Verify the ticket number in the request path.", "value": { "error": { "code": "TICKET_NOT_FOUND", "message": "The requested ticket could not be found" } } } } } } }, "409": { "description": "The ticket was merged into another ticket, or it is closed and cannot be reopened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "TICKET_MERGED": { "summary": "This ticket was merged into another ticket. It no longer accepts replies, and its status can only move between closed statuses. Continue on the ticket it was merged into.", "value": { "error": { "code": "TICKET_MERGED", "message": "The ticket was merged into another ticket" } } }, "TICKET_CLOSED": { "summary": "This ticket is closed or cancelled and its conversation was handed over from the AI agent, so it accepts no replies and cannot be reopened. It can still move between closed and cancelled statuses. To keep talking to the customer, reply on the conversation's open ticket, or take over the conversation from the dashboard to open a new one.", "value": { "error": { "code": "TICKET_CLOSED", "message": "The ticket is closed and cannot be reopened or replied to" } } } } } } }, "422": { "description": "The requested statusId/assignee/teamId either doesn't belong to this agent or account, or (for the assignee) was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "TICKET_INVALID_STATUS": { "summary": "`statusId` does not belong to a status for this agent. Discover valid ids via GET /ticket-statuses.", "value": { "error": { "code": "TICKET_INVALID_STATUS", "message": "The requested status could not be applied" } } }, "TICKET_TEAM_MEMBER_NOT_FOUND": { "summary": "Neither `assigneeId` nor `assigneeEmail` resolved to a team member on this account.", "value": { "error": { "code": "TICKET_TEAM_MEMBER_NOT_FOUND", "message": "The requested assignee could not be found" } } }, "TICKET_TEAM_NOT_FOUND": { "summary": "`teamId` does not belong to a team for this agent. Discover valid ids via GET /teams.", "value": { "error": { "code": "TICKET_TEAM_NOT_FOUND", "message": "The requested team could not be found" } } } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } } } } }, "/agents/{agentId}/helpdesk/tickets/{ticketNumber}/messages": { "get": { "operationId": "listTicketMessages", "x-mcp": { "tool": "chatbase_list_ticket_messages", "scopes": [ "helpdesk_tickets:read" ], "annotations": { "readOnly": true, "idempotent": true }, "fields": [ "id", "type", "sender", "contentText", "attachments", "createdAt", "metadata" ], "maxItems": 50 }, "tags": [ "Helpdesk" ], "summary": "List ticket messages", "description": "Returns a ticket's message thread in chronological order. Supports cursor-based pagination.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647, "description": "The ticket number", "example": 123 }, "required": true, "description": "The ticket number", "name": "ticketNumber", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor from a previous response to fetch the next page", "example": "eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMC4wMDBaIiwiaWQiOiJhYmMxMjMifQ==" }, "required": false, "description": "Opaque cursor from a previous response to fetch the next page", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Number of items per page (1 to 100, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1 to 100, default 20)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "default": "reply,note", "description": "Comma-separated message types. Defaults to `reply,note`; system `event` messages are opt-in.", "example": "reply,note" }, "required": false, "description": "Comma-separated message types. Defaults to `reply,note`; system `event` messages are opt-in.", "name": "types", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc", "description": "Chronological direction. Defaults to `asc`, so a thread reads oldest-first. A cursor is only valid for the direction it was issued with.", "example": "asc" }, "required": false, "description": "Chronological direction. Defaults to `asc`, so a thread reads oldest-first. A cursor is only valid for the direction it was issued with.", "name": "order", "in": "query" } ], "responses": { "200": { "description": "Paginated list of messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTicketMessagesResponse" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "The agent could not be found (or does not belong to the authenticated account), or the ticket number does not exist for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "AGENT_NOT_FOUND": { "summary": "No agent matches the provided `agentId`, or it does not belong to the authenticated account.", "value": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found" } } }, "TICKET_NOT_FOUND": { "summary": "No ticket matches the provided ticket number for this agent. Verify the ticket number in the request path.", "value": { "error": { "code": "TICKET_NOT_FOUND", "message": "The requested ticket could not be found" } } } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } }, "post": { "operationId": "createTicketMessage", "x-mcp": { "tool": "chatbase_create_ticket_message", "scopes": [ "helpdesk_tickets:write" ], "annotations": {} }, "tags": [ "Helpdesk" ], "summary": "Add a message to a ticket", "description": "Posts an agent reply to a ticket on behalf of a team member. Delivery to the customer is asynchronous; a 201 confirms the reply was recorded, not delivered. Posting a reply may transition the ticket status, matching dashboard behavior.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The agent ID", "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "description": "The agent ID", "name": "agentId", "in": "path" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2147483647, "description": "The ticket number", "example": 123 }, "required": true, "description": "The ticket number", "name": "ticketNumber", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTicketMessageBody" } } } }, "responses": { "201": { "description": "The created message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedTicketMessage" } } } }, "400": { "description": "The request body failed schema validation. Inspect the `details` object in the error response for field-level errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Invalid request" } } } } }, "401": { "description": "No Authorization header present. Provide a valid API key as a Bearer token in the Authorization header: `Authorization: Bearer `.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "Authentication required" } } } } }, "403": { "description": "Your current plan does not include API access. Upgrade to the Basic plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Basic plan or higher is required to access the API" } } } } }, "404": { "description": "No ticket matches the provided ticket number for this agent. Verify the ticket number in the request path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "TICKET_NOT_FOUND", "message": "The requested ticket could not be found" } } } } }, "409": { "description": "The ticket cannot take a human reply: its conversation is not taken over, the ticket was merged into another ticket, or the ticket is closed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "CONVERSATION_NOT_TAKEN_OVER": { "summary": "This ticket is linked to a live conversation that has not been taken over from the AI agent, so a human reply cannot be posted. Take over the conversation from the dashboard first.", "value": { "error": { "code": "CONVERSATION_NOT_TAKEN_OVER", "message": "The linked conversation is not taken over" } } }, "TICKET_MERGED": { "summary": "This ticket was merged into another ticket. It no longer accepts replies, and its status can only move between closed statuses. Continue on the ticket it was merged into.", "value": { "error": { "code": "TICKET_MERGED", "message": "The ticket was merged into another ticket" } } }, "TICKET_CLOSED": { "summary": "This ticket is closed or cancelled and its conversation was handed over from the AI agent, so it accepts no replies and cannot be reopened. It can still move between closed and cancelled statuses. To keep talking to the customer, reply on the conversation's open ticket, or take over the conversation from the dashboard to open a new one.", "value": { "error": { "code": "TICKET_CLOSED", "message": "The ticket is closed and cannot be reopened or replied to" } } } } } } }, "422": { "description": "The authorId or authorEmail does not resolve to a member of your account. Authors must be existing team members. Also returned with code `MESSAGE_CONTENT_NOT_RENDERABLE` when the message body renders to empty HTML.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "TEAM_MEMBER_NOT_FOUND", "message": "No team member matches the provided author" } } } } }, "429": { "description": "Rate limit exceeded. Check the `X-RateLimit-Reset` response header for the Unix epoch seconds when the limit resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Too many requests, please try again later" } } } } }, "500": { "description": "An unhandled server error occurred. If the issue persists, contact support with the `x-request-id` response header value for debugging.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Something went wrong, please try again" } } } } }, "503": { "description": "Chatbase is undergoing scheduled maintenance and the API is temporarily rejecting requests. This is transient; retry after a short delay. Requests are rejected before any data is read or written, so no partial changes are applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SERVICE_UNDER_MAINTENANCE", "message": "The API is temporarily unavailable for scheduled maintenance, please try again later" } } } } } } } }, "/api/v2/agents/{agentId}/sources": { "post": { "operationId": "createFileSource", "tags": [ "Sources" ], "summary": "Create file source", "description": "Upload a file as a knowledge source for an agent. Accepts PDF, DOC, DOCX, and TXT files up to 20 MB.\n\n**Base URL:** `https://files.chatbase.co/api/v2` — this endpoint uses a different host from all other Sources endpoints.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "name": "agentId", "in": "path", "description": "The agent ID" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Display name for the source.", "example": "Employee Handbook" }, "file": { "type": "string", "format": "binary", "description": "File to upload. Formats: .pdf, .doc, .docx, .txt. Max 20 MB." } }, "required": [ "name", "file" ] } } } }, "responses": { "201": { "description": "File source created. Status is `untrained` until the agent is retrained.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceListItem" }, "example": { "id": "a63a69a5-e7a9-4757-b73b-2041854d435d", "type": "file", "name": "Employee Handbook", "size": 245760, "createdAt": "2025-01-15T10:30:00.000Z", "status": "untrained", "metadata": null } } } }, "400": { "description": "Missing required field, unsupported file type, or a file outside the allowed size range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Missing required field, unsupported file type, or a file outside the allowed size range." } } } } }, "401": { "description": "No Authorization header present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "No Authorization header present." } } } } }, "403": { "description": "Basic plan or higher required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "Basic plan or higher required." } } } } }, "404": { "description": "Agent not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_NOT_FOUND", "message": "Agent not found." } } } } }, "422": { "description": "Adding this file would exceed the plan storage limit for this agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_SIZE_LIMIT_EXCEEDED", "message": "Adding this file would exceed the plan storage limit for this agent." } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Rate limit exceeded." } } } } }, "500": { "description": "Unhandled server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unhandled server error." } } } } } }, "servers": [ { "url": "https://files.chatbase.co", "description": "Chatbase file upload server" } ] } }, "/api/v2/agents/{agentId}/sources/{sourceId}": { "put": { "operationId": "updateFileSource", "tags": [ "Sources" ], "summary": "Update file source", "description": "Replace a file source's content, rename it, or both. At least one of `name` or `file` must be provided.\n\n**Base URL:** `https://files.chatbase.co/api/v2` — this endpoint uses a different host from all other Sources endpoints.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "5QHA6VB-DIAbBhxwqxfdi" }, "required": true, "name": "agentId", "in": "path", "description": "The agent ID" }, { "schema": { "type": "string", "minLength": 1, "example": "a63a69a5-e7a9-4757-b73b-2041854d435d" }, "required": true, "name": "sourceId", "in": "path", "description": "The source ID" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "New display name. If omitted, the existing name is preserved.", "example": "Employee Handbook v2" }, "file": { "type": "string", "format": "binary", "description": "Replacement file. Same constraints as create. If omitted, existing content is preserved." } } } } } }, "responses": { "200": { "description": "Updated file source. If the file was replaced and previously `trained`, status becomes `updated`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceListItem" }, "example": { "id": "a63a69a5-e7a9-4757-b73b-2041854d435d", "type": "file", "name": "Employee Handbook v2", "size": 261120, "createdAt": "2025-01-15T10:30:00.000Z", "status": "updated", "metadata": null } } } }, "400": { "description": "No fields provided, unsupported file type, or a file outside the allowed size range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "No fields provided, unsupported file type, or a file outside the allowed size range." } } } } }, "401": { "description": "No Authorization header present.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AUTH_MISSING_API_KEY", "message": "No Authorization header present." } } } } }, "403": { "description": "Basic plan or higher required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "Basic plan or higher required." } } } } }, "404": { "description": "Agent or source not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_NOT_FOUND", "message": "Agent or source not found." } } } } }, "409": { "description": "Source is pending deletion. Restore it before editing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_PENDING_DELETION", "message": "Source is pending deletion. Restore it before editing." } } } } }, "422": { "description": "Adding this file would exceed the plan storage limit for this agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_SIZE_LIMIT_EXCEEDED", "message": "Adding this file would exceed the plan storage limit for this agent." } } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "RATE_LIMIT_TOO_MANY_REQUESTS", "message": "Rate limit exceeded." } } } } }, "500": { "description": "Unhandled server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_SERVER_ERROR", "message": "Unhandled server error." } } } } } }, "servers": [ { "url": "https://files.chatbase.co", "description": "Chatbase file upload server" } ] } } }, "webhooks": {} }