{ "openapi": "3.1.0", "info": { "title": "Chatbase API v2", "version": "2.0.0", "description": "Chatbase API v2 - A robust, structured API for managing agents and conversations." }, "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" } } } ] } }, "description": "Per-channel instruction overrides" }, "model": { "type": "string", "enum": [ "gpt-4o", "gpt-4o-mini", "o4-mini", "gpt-oss-120b", "gpt-oss-20b", "gpt-5", "gpt-5.1", "gpt-5.2", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5-mini", "gpt-5-nano", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-opus-4-5", "claude-haiku-4-5", "claude-sonnet-4-5", "gemini-2.5-pro", "gemini-3-flash", "gemini-3.1-flash-lite", "gemini-3.1-pro", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.6-flash", "grok-3", "grok-3-mini", "grok-4", "DeepSeek-V3", "DeepSeek-R1", "DeepSeek-V4-Flash", "Llama-4-Scout-17B-16E-Instruct", "Llama-4-Maverick-17B-128E-Instruct-FP8", "kimi-k2", "mistral-medium-3.5", "mistral-small-2603", "glm-5.2" ], "description": "AI model used by the agent", "example": "gpt-5.1" }, "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)" }, "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" }, "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", "gpt-4o-mini", "o4-mini", "gpt-oss-120b", "gpt-oss-20b", "gpt-5", "gpt-5.1", "gpt-5.2", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5-mini", "gpt-5-nano", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-opus-4-5", "claude-haiku-4-5", "claude-sonnet-4-5", "gemini-2.5-pro", "gemini-3-flash", "gemini-3.1-flash-lite", "gemini-3.1-pro", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.6-flash", "grok-3", "grok-3-mini", "grok-4", "DeepSeek-V3", "DeepSeek-R1", "DeepSeek-V4-Flash", "Llama-4-Scout-17B-16E-Instruct", "Llama-4-Maverick-17B-128E-Instruct-FP8", "kimi-k2", "mistral-medium-3.5", "mistral-small-2603", "glm-5.2", "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 } }, "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", "null" ], "description": "Current training status of the agent", "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", "notificationsSettings", "ipRateLimits", "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" ] }, "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 }, "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" }, "tintedGrayscale": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "hue": { "type": "number", "minimum": 0, "maximum": 360, "default": 0 }, "tint": { "type": "number", "minimum": 0, "maximum": 10, "default": 0 }, "shade": { "type": "number", "minimum": 0, "maximum": 10, "default": 0 } } }, "accentColor": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "color": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i", "default": "#09090B" } } }, "customSurfaceColors": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "background": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i", "default": "#FFFFFF" }, "foreground": { "type": "string", "pattern": "^#([0-9A-F]{3}){1,2}$/i", "default": "#FFFFFF" } } }, "typography": { "type": "object", "properties": { "fontFamily": { "type": "string", "pattern": "^[a-zA-Z0-9 ,'\"_-]+$", "default": "Inter" }, "fontSize": { "type": "string", "pattern": "^\\d+(\\.\\d+)?(px|rem|em)$", "default": "16px" } } }, "width": { "type": "string", "enum": [ "small", "medium", "large" ], "default": "medium" }, "closeOnOutsideClick": { "type": "boolean", "default": true }, "notificationIndicator": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "number": { "type": "integer", "minimum": 0, "maximum": 99, "default": 1 } } }, "notificationMessage": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "text": { "type": "string", "maxLength": 200, "default": "" } } } }, "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", "description": "System prompt / instructions for the agent" }, "model": { "type": "string", "enum": [ "gpt-4o", "gpt-4o-mini", "o4-mini", "gpt-oss-120b", "gpt-oss-20b", "gpt-5", "gpt-5.1", "gpt-5.2", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5-mini", "gpt-5-nano", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-opus-4-5", "claude-haiku-4-5", "claude-sonnet-4-5", "gemini-2.5-pro", "gemini-3-flash", "gemini-3.1-flash-lite", "gemini-3.1-pro", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.6-flash", "grok-3", "grok-3-mini", "grok-4", "DeepSeek-V3", "DeepSeek-R1", "DeepSeek-V4-Flash", "Llama-4-Scout-17B-16E-Instruct", "Llama-4-Maverick-17B-128E-Instruct-FP8", "kimi-k2", "mistral-medium-3.5", "mistral-small-2603", "glm-5.2" ], "description": "AI model to use", "example": "gpt-5.1" }, "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", "description": "System prompt" }, "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" } } } ] } }, "description": "Per-channel instruction overrides" }, "model": { "type": "string", "enum": [ "gpt-4o", "gpt-4o-mini", "o4-mini", "gpt-oss-120b", "gpt-oss-20b", "gpt-5", "gpt-5.1", "gpt-5.2", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5-mini", "gpt-5-nano", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-opus-4-5", "claude-haiku-4-5", "claude-sonnet-4-5", "gemini-2.5-pro", "gemini-3-flash", "gemini-3.1-flash-lite", "gemini-3.1-pro", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.6-flash", "grok-3", "grok-3-mini", "grok-4", "DeepSeek-V3", "DeepSeek-R1", "DeepSeek-V4-Flash", "Llama-4-Scout-17B-16E-Instruct", "Llama-4-Maverick-17B-128E-Instruct-FP8", "kimi-k2", "mistral-medium-3.5", "mistral-small-2603", "glm-5.2" ], "description": "AI model", "example": "gpt-5.1" }, "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)" }, "voiceSettings": { "type": [ "object", "null" ], "properties": { "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", "Maya", "Ruby", "Nina", "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", "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-4o", "gpt-4o-mini", "o4-mini", "gpt-oss-120b", "gpt-oss-20b", "gpt-5", "gpt-5.1", "gpt-5.2", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano", "gpt-5.5", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5-mini", "gpt-5-nano", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-opus-4-5", "claude-haiku-4-5", "claude-sonnet-4-5", "gemini-2.5-pro", "gemini-3-flash", "gemini-3.1-flash-lite", "gemini-3.1-pro", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.6-flash", "grok-3", "grok-3-mini", "grok-4", "DeepSeek-V3", "DeepSeek-R1", "DeepSeek-V4-Flash", "Llama-4-Scout-17B-16E-Instruct", "Llama-4-Maverick-17B-128E-Instruct-FP8", "kimi-k2", "mistral-medium-3.5", "mistral-small-2603", "glm-5.2" ], "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-4o-mini" }, "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)." } }, "description": "Voice mode configuration (null = disable voice mode)" } } }, "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" ], "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" ] }, "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" ] }, "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" ], "description": "Conversation activity status" } }, "required": [ "id", "title", "createdAt", "updatedAt", "userId", "status" ] }, "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", "Iframe", "Email", "Agent page", "Phone", "Android SDK", "iOS SDK", "Unspecified", null ], "description": "Conversation source" }, "status": { "type": "string", "enum": [ "ongoing", "ended", "taken_over" ], "description": "Conversation activity status" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ExportMessage" }, "description": "Conversation messages" } }, "required": [ "id", "title", "createdAt", "updatedAt", "userId", "source", "status", "messages" ] }, "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)" }, "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" ] }, "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" ], "description": "Training status of the source" }, "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", "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" } } } ] } }, "parameters": {} }, "paths": { "/health": { "get": { "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": { "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–100, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1–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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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 Standard 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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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}/clone": { "post": { "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "tags": [ "Agents" ], "summary": "Train agent", "description": "Queues a training job for the agent. Training is asynchronous — use GET /agents/{agentId} to poll `status` for completion.", "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": "Training job queued", "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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 training run is already in progress for this agent. Wait for it to complete before starting another.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "AGENT_ALREADY_TRAINING", "message": "Agent is already training, please wait for it to finish" } } } } }, "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}/chat": { "post": { "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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}/conversations": { "get": { "tags": [ "Conversations" ], "summary": "List conversations", "description": "List conversations for an agent, ordered by createdAt date. 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", "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–100, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1–100, default 20)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Paginated list of conversations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListConversationsResponse" } } } }, "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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.", "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" } ], "responses": { "200": { "description": "Paginated list of conversations with full message history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportConversationsResponse" } } } }, "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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}": { "get": { "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.", "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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}/conversations/{conversationId}/messages": { "get": { "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–100, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1–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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "tags": [ "Conversations" ], "summary": "List conversations for a user", "description": "List conversations for a specific user under an agent, ordered by last activity. 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–100, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1–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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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–100, default 20)", "example": 20 }, "required": false, "description": "Number of items per page (1–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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "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.\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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard plan or higher is required to access the API" } } } } }, "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 or upgrade your plan.", "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": { "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "tags": [ "Sources" ], "summary": "Delete source", "description": "Marks a source for deletion. Returns the source in its final state.", "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": { "tags": [ "Sources" ], "summary": "Update source", "description": "Updates an existing source. Accepts text, qna, and link sources. File sources require a dedicated endpoint. 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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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 or upgrade your plan.", "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": { "tags": [ "Sources" ], "summary": "Restore source", "description": "Restores a source that is pending deletion back to its previous active state.", "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 restored to its previous active state", "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 Standard plan or higher to use the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "A Standard 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": "Only sources with status to_be_deleted can be restored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_NOT_RESTORABLE", "message": "Source is not pending deletion" } } } } }, "422": { "description": "Restoring this link would exceed the maximum number of crawl and sitemap links allowed per agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_LINK_LIMIT_EXCEEDED", "message": "Crawl/sitemap link limit reached" } } } } }, "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": { "tags": [ "Sources" ], "summary": "Create file source", "operationId": "createFileSource", "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": [ { "name": "agentId", "in": "path", "required": true, "description": "The agent ID", "schema": { "type": "string", "minLength": 1, "example": "5QHA6VB-DIAbBhxwqxfdi" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "name", "file" ], "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." } } } } } }, "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 or unsupported file type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "Missing required field or unsupported file type." } } } } }, "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": "Standard plan or higher required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "Standard 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": "File would exceed the plan storage limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_SIZE_LIMIT_EXCEEDED", "message": "File would exceed the plan storage limit." } } } } }, "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": { "tags": [ "Sources" ], "summary": "Update file source", "operationId": "updateFileSource", "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": [ { "name": "agentId", "in": "path", "required": true, "description": "The agent ID", "schema": { "type": "string", "minLength": 1, "example": "5QHA6VB-DIAbBhxwqxfdi" } }, { "name": "sourceId", "in": "path", "required": true, "description": "The source ID", "schema": { "type": "string", "minLength": 1, "example": "a63a69a5-e7a9-4757-b73b-2041854d435d" } } ], "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 or unsupported file type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "VALIDATION_INVALID_BODY", "message": "No fields provided or unsupported file type." } } } } }, "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": "Standard plan or higher required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SUBSCRIPTION_API_RESTRICTED_PLAN", "message": "Standard plan or higher required." } } } } }, "404": { "description": "Source not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_NOT_FOUND", "message": "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": "File would exceed the plan storage limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "SOURCE_SIZE_LIMIT_EXCEEDED", "message": "File would exceed the plan storage limit." } } } } }, "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": {} }