{ "openapi": "3.1.0", "info": { "title": "MonCha API Vendor", "version": "2026-09-26" }, "servers": [ { "url": "https://api.dev-moncha.com/vendor/v1" } ], "security": [ { "vendorBearer": [], "vendorTenant": [] } ], "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, "Tier": { "type": "string", "enum": [ "starter", "growth", "scale" ] }, "Slot": { "type": "object", "properties": { "allocated": { "type": "number" }, "used": { "type": "number" }, "available": { "type": "number" } }, "required": [ "allocated", "used", "available" ], "additionalProperties": false }, "Bot": { "type": "object", "properties": { "bot_id": { "type": "string", "format": "uuid" }, "customer_tenant_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "plan_tier": { "$ref": "#/components/schemas/Tier" }, "is_active": { "type": "boolean" }, "vendor_deactivated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "bot_id", "customer_tenant_id", "name", "plan_tier", "is_active", "vendor_deactivated_at" ], "additionalProperties": false }, "Customer": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid" }, "customer_tenant_id": { "type": "string", "format": "uuid" }, "external_customer_id": { "type": "string" }, "connected_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "connection_id", "customer_tenant_id", "external_customer_id", "connected_at", "name", "email" ], "additionalProperties": false }, "BotCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 30 }, "plan_tier": { "$ref": "#/components/schemas/Tier" }, "language": { "type": "string", "minLength": 2, "maxLength": 10, "default": "en" } }, "required": [ "name", "plan_tier" ], "additionalProperties": false }, "BotSettings": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "modelTier": { "type": "string", "enum": [ "fast", "quality" ] }, "language": { "type": "string", "minLength": 2, "maxLength": 10 }, "languageMode": { "type": "string", "enum": [ "match", "fixed" ] }, "supportedLanguages": { "maxItems": 40, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 10 } }, "fallbackMessage": { "type": "string", "maxLength": 500 }, "historyMessages": { "type": "integer", "minimum": 0, "maximum": 6 }, "instructions": { "type": "string", "maxLength": 4000 }, "instructionPreset": { "type": "string", "maxLength": 40 }, "persona": { "type": "string", "maxLength": 2000 }, "personaPreset": { "type": "string", "maxLength": 40 }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "collectUserData": { "type": "string", "enum": [ "mandatory", "optional", "off" ] }, "collectFields": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "name", "email", "phone" ] } }, "captureMode": { "type": "string", "enum": [ "off", "passive", "conversational", "form" ] }, "leadGoal": { "type": "string", "maxLength": 2000 }, "notifyThreshold": { "type": "integer", "minimum": 0, "maximum": 100 }, "translations": { "type": "object", "propertyNames": { "type": "string", "minLength": 2, "maxLength": 10 }, "additionalProperties": { "type": "object", "properties": { "fallbackMessage": { "type": "string", "maxLength": 500 } }, "additionalProperties": false } } }, "additionalProperties": false }, "WidgetConfig": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "botName": { "type": "string", "minLength": 1, "maxLength": 30 }, "tooltip": { "type": "string", "maxLength": 300 }, "welcomeMessage": { "type": "string", "maxLength": 500 }, "inputPlaceholder": { "type": "string", "maxLength": 80 }, "primaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "linkColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "iconBgColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "botAvatarBgColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "voiceOrbColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "transparentIconBg": { "type": "boolean" }, "launcherIconUrl": { "type": "string", "format": "uri" }, "botIconUrl": { "type": "string", "format": "uri" }, "userIconUrl": { "type": "string", "format": "uri" }, "agentIconUrl": { "type": "string", "format": "uri" }, "showExpand": { "type": "boolean" }, "fontSize": { "type": "integer", "minimum": 11, "maximum": 20 }, "chatHeightPct": { "type": "integer", "minimum": 40, "maximum": 100 }, "darkMode": { "type": "boolean" }, "autoOpenDesktopSec": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 120 }, { "type": "null" } ] }, "autoOpenMobileSec": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 120 }, { "type": "null" } ] }, "requireTerms": { "type": "boolean" }, "termsUrl": { "type": "string", "format": "uri" }, "disclaimerText": { "type": "string", "maxLength": 500 }, "rtl": { "type": "boolean" }, "externalLinkUrl": { "type": "string", "format": "uri" }, "chatDisabled": { "type": "boolean" }, "disabledMessage": { "type": "string", "maxLength": 300 }, "maxMessagesPerConversation": { "type": "integer", "minimum": 0, "maximum": 100 }, "showDownload": { "type": "boolean" }, "iconSize": { "type": "string", "enum": [ "small", "medium", "large" ] }, "iconShape": { "type": "string", "enum": [ "circle", "square", "rounded" ] }, "position": { "type": "string", "enum": [ "bottom-right", "bottom-left" ] }, "offsetBottom": { "type": "integer", "minimum": 0, "maximum": 200 }, "offsetSide": { "type": "integer", "minimum": 0, "maximum": 200 }, "offsetBottomMobile": { "type": "integer", "minimum": 0, "maximum": 200 }, "offsetSideMobile": { "type": "integer", "minimum": 0, "maximum": 200 }, "launcherShade": { "type": "integer", "minimum": 0, "maximum": 100 }, "hideBranding": { "type": "boolean" }, "hideSources": { "type": "boolean" }, "hideFeedback": { "type": "boolean" }, "hideRefresh": { "type": "boolean" }, "hideTooltip": { "type": "boolean" }, "voiceMode": { "type": "boolean" }, "ticketDepartments": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "boolean" } }, "watermarkLink": { "type": "string", "format": "uri" }, "watermarkIconUrl": { "type": "string", "format": "uri" }, "quickPrompts": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "followUpChips": { "type": "boolean" }, "followUpPrompts": { "maxItems": 3, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "strings": { "type": "object", "properties": { "online": { "type": "string", "maxLength": 40 }, "welcome": { "type": "string", "maxLength": 500 }, "placeholder": { "type": "string", "maxLength": 80 }, "errorGeneric": { "type": "string", "maxLength": 200 }, "errorNoResponse": { "type": "string", "maxLength": 200 }, "poweredBy": { "type": "string", "maxLength": 60 }, "openChat": { "type": "string", "maxLength": 60 }, "closeChat": { "type": "string", "maxLength": 60 }, "send": { "type": "string", "maxLength": 40 }, "startVoice": { "type": "string", "maxLength": 80 }, "stopVoice": { "type": "string", "maxLength": 80 }, "recording": { "type": "string", "maxLength": 40 }, "talkToHuman": { "type": "string", "maxLength": 60 }, "handoffSent": { "type": "string", "maxLength": 200 }, "handoffFailed": { "type": "string", "maxLength": 200 }, "fieldName": { "type": "string", "maxLength": 40 }, "fieldEmail": { "type": "string", "maxLength": 40 }, "fieldPhone": { "type": "string", "maxLength": 40 }, "submit": { "type": "string", "maxLength": 40 }, "skip": { "type": "string", "maxLength": 40 }, "leadThanks": { "type": "string", "maxLength": 200 } }, "additionalProperties": false }, "bookingEnabled": { "type": "boolean" }, "bookingConfig": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 60 }, "requireNotes": { "type": "boolean" }, "extraFields": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 40 }, "label": { "type": "string", "maxLength": 60 }, "required": { "type": "boolean" } }, "required": [ "key", "label", "required" ], "additionalProperties": false } }, "hoursStart": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "hoursEnd": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" }, "slotMinutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "visitorPicksTime": { "type": "boolean" }, "mapsUrl": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false }, "homeChannels": { "maxItems": 1, "type": "array", "items": {} }, "translations": { "type": "object", "propertyNames": { "type": "string", "minLength": 2, "maxLength": 10 }, "additionalProperties": { "type": "object", "properties": { "welcomeMessage": { "type": "string", "maxLength": 500 }, "tooltip": { "type": "string", "maxLength": 300 }, "quickPrompts": { "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } } }, "additionalProperties": false } } }, "additionalProperties": false }, "Training": { "type": "object", "properties": { "training_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "partial_failure", "failed" ] }, "total": { "type": "integer" }, "ready": { "type": "integer" }, "failed": { "type": "integer" }, "document_id": { "type": "string", "format": "uuid" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeDocument" } }, "poll_after_seconds": { "type": "integer" } }, "required": [ "training_id", "status" ], "additionalProperties": false }, "KnowledgeDocument": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "source_type": { "type": "string" }, "content": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "ready", "failed" ] }, "chunk_count": { "type": "integer" }, "pages_count": { "type": "integer" }, "synced_at": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "status", "chunk_count", "pages_count" ], "additionalProperties": false }, "DocumentInput": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "text": { "type": "string", "minLength": 1, "maxLength": 200000 }, "source_type": { "type": "string", "enum": [ "url", "qa", "snippet" ], "default": "url" }, "scrape_options": { "type": "object", "properties": { "extractMainOnly": { "type": "boolean" }, "includeSelectors": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 30 }, "excludeSelectors": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 30 } }, "required": [], "additionalProperties": false } }, "required": [ "title" ], "additionalProperties": false, "oneOf": [ { "required": [ "url" ], "not": { "required": [ "text" ] } }, { "required": [ "text" ], "not": { "required": [ "url" ] } } ] }, "TicketMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "ticket_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "author_type": { "type": "string" }, "author_id": { "type": [ "string", "null" ] }, "author_name": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "attachment_url": { "type": [ "string", "null" ] }, "attachment_type": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "ticket_id", "tenant_id", "author_type", "author_id", "author_name", "body", "attachment_url", "attachment_type", "created_at" ], "additionalProperties": false }, "Message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "role": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "feedback": { "type": [ "string", "null" ] } }, "required": [ "id", "role", "content", "created_at", "feedback" ], "additionalProperties": false }, "Conversation": { "type": "object", "properties": { "session_id": { "type": "string" }, "message_count": { "type": "number" }, "last_at": { "type": "string", "format": "date-time" } }, "required": [ "session_id", "message_count", "last_at" ], "additionalProperties": false }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "is_guest": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "email", "is_guest", "created_at" ], "additionalProperties": false }, "Lead": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "chatbot_id": { "type": [ "string", "null" ] }, "session_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "external_user_id": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "intent_category": { "type": [ "string", "null" ] }, "intent_summary": { "type": [ "string", "null" ] }, "sentiment": { "type": [ "string", "null" ] }, "notified_at": { "type": [ "string", "null" ] }, "asked_contact_at": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "score": { "type": "number" }, "score_band": { "type": "string", "enum": [ "hot", "warm", "cold" ] }, "qualification": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "status": { "type": "string", "enum": [ "new", "contacted", "qualified", "won", "lost" ] }, "captured_via": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "channel": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "chatbot_id", "session_id", "name", "email", "phone", "external_user_id", "company", "intent_category", "intent_summary", "sentiment", "notified_at", "asked_contact_at", "notes", "country", "region", "score", "score_band", "qualification", "status", "captured_via", "confidence", "channel", "created_at", "updated_at" ], "additionalProperties": true }, "Ticket": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "chatbot_id": { "type": [ "string", "null" ] }, "session_id": { "type": [ "string", "null" ] }, "subject": { "type": "string" }, "department": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "in_progress", "resolved", "closed" ] }, "priority": { "type": "string" }, "assigned_to": { "type": [ "string", "null" ] }, "agent_unread": { "type": "boolean" }, "visitor_unread": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "last_message_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "contact_id", "chatbot_id", "session_id", "subject", "department", "status", "priority", "assigned_to", "agent_unread", "visitor_unread", "created_at", "updated_at", "last_message_at" ], "additionalProperties": true, "description": "List responses additionally include contact_name and contact_email." }, "Booking": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "chatbot_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "requested_slot": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "time_zone": { "type": [ "string", "null" ] }, "rejection_comment": { "type": [ "string", "null" ] }, "confirmed_at": { "type": [ "string", "null" ] }, "rejected_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "custom_fields": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "status": { "type": "string", "enum": [ "pending", "confirmed", "rejected", "cancelled" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "tenant_id", "chatbot_id", "name", "email", "phone", "notes", "requested_slot", "country", "time_zone", "rejection_comment", "confirmed_at", "rejected_at", "cancelled_at", "custom_fields", "status", "created_at" ], "additionalProperties": true }, "Function": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string" }, "url": { "type": "string" }, "params": { "type": "object", "additionalProperties": { "type": "string" } }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "tenant_id": { "type": "string", "format": "uuid" }, "chatbot_id": { "type": [ "string", "null" ] }, "vendor_connection_id": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "description", "method", "url", "params", "is_active", "created_at" ], "additionalProperties": false }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "last_status": { "type": [ "number", "null" ] }, "last_triggered_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "secret": { "type": "string" }, "tenant_id": { "type": "string", "format": "uuid" }, "chatbot_id": { "type": [ "string", "null" ] }, "vendor_connection_id": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "events", "is_active", "last_status", "last_triggered_at", "created_at" ], "additionalProperties": false }, "Channel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "phone_number": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "ai_enabled": { "type": "boolean" }, "show_on_widget": { "type": "boolean" } }, "required": [ "id", "phone_number", "display_name", "status", "ai_enabled", "show_on_widget" ], "additionalProperties": false }, "InboxThread": { "type": "object", "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string" }, "subject": { "type": "string" }, "visitor": { "type": "string" }, "last_at": { "type": "string", "format": "date-time" }, "inbound_count": { "type": "number" }, "outbound_count": { "type": "number" } }, "required": [ "conversation_id", "session_id", "subject", "visitor", "last_at", "inbound_count", "outbound_count" ], "additionalProperties": false }, "Analytics": { "type": "object", "properties": { "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "user_messages": { "type": "number" }, "assistant_messages": { "type": "number" } }, "required": [ "day", "user_messages", "assistant_messages" ], "additionalProperties": false } }, "top_questions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "times": { "type": "number" } }, "required": [ "question", "times" ], "additionalProperties": false } }, "unanswered": { "type": "object", "properties": { "count": { "type": "number" }, "total": { "type": "number" }, "rate": { "type": "number" } }, "required": [ "count", "total", "rate" ], "additionalProperties": false }, "feedback": { "type": "object", "properties": { "positive": { "type": "number" }, "negative": { "type": "number" } }, "required": [ "positive", "negative" ], "additionalProperties": false }, "sessions": { "type": "object", "properties": { "total": { "type": "number" }, "avg_messages": { "type": "number" } }, "required": [ "total", "avg_messages" ], "additionalProperties": false } }, "required": [ "daily", "top_questions", "unanswered", "feedback", "sessions" ], "additionalProperties": false }, "Summary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "message_count": { "type": "number" }, "session_count": { "type": "number" }, "insights": { "type": "object", "properties": { "topQuestions": { "type": "array", "items": { "type": "string" } }, "problems": { "type": "array", "items": { "type": "string" } }, "praise": { "type": "array", "items": { "type": "string" } } }, "required": [ "topQuestions", "problems", "praise" ], "additionalProperties": false } }, "required": [ "id", "period_start", "period_end", "message_count", "session_count", "insights" ], "additionalProperties": false }, "SummarySettings": { "anyOf": [ { "type": "object", "properties": { "intervalDays": { "type": "integer", "enum": [ 30, 90 ] }, "nextDueAt": { "type": "string", "format": "date-time" }, "lastSyncedAt": { "type": [ "string", "null" ] } }, "required": [ "intervalDays", "nextDueAt", "lastSyncedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "Plan": { "type": "object", "properties": { "id": { "type": "string" }, "message_limit": { "type": "number" }, "pages_limit": { "type": "number" }, "voice_minutes_limit": { "type": "number" }, "api_access": { "type": "boolean" }, "webhooks": { "type": "boolean" }, "auto_sync_interval": { "type": [ "string", "null" ] } }, "additionalProperties": true, "description": "Resolved bot tier catalog with enterprise feature restrictions; -1 means unlimited." } }, "securitySchemes": { "vendorBearer": { "type": "http", "scheme": "bearer" }, "vendorTenant": { "type": "apiKey", "in": "header", "name": "X-Vendor-Tenant-Id" } } }, "paths": { "/account": { "get": { "summary": "Enterprise name and vendor tenant ID", "description": "Scope: customers:read. none. Response: { tenant_id: UUID, name: string }", "parameters": [], "responses": { "200": { "description": "{ tenant_id: UUID, name: string }", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "tenant_id", "name" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/slots": { "get": { "summary": "Contract capacity and occupied slots by tier", "description": "Scope: bots:read. none. Response: { data: { starter: Slot, growth: Slot, scale: Slot } }", "parameters": [], "responses": { "200": { "description": "{ data: { starter: Slot, growth: Slot, scale: Slot } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "starter": { "$ref": "#/components/schemas/Slot" }, "growth": { "$ref": "#/components/schemas/Slot" }, "scale": { "$ref": "#/components/schemas/Slot" } }, "required": [ "starter", "growth", "scale" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/connect/sessions": { "post": { "summary": "Start branded browser authorization", "description": "Scope: connect:write. { external_customer_id: string(1..200), redirect_uri: registered URL, state: string(32..256), code_challenge: PKCE S256 base64url(43), scopes?: Scope[] }. Response: { authorization_url: URL, expires_in: 600 }", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_customer_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "redirect_uri": { "type": "string", "format": "uri" }, "state": { "type": "string", "minLength": 32, "maxLength": 256 }, "code_challenge": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "external_customer_id", "redirect_uri", "state", "code_challenge" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "{ authorization_url: URL, expires_in: 600 }", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorization_url": { "type": "string" }, "expires_in": { "type": "integer" } }, "required": [ "authorization_url", "expires_in" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/connect/exchange": { "post": { "summary": "Exchange a single-use code on your backend", "description": "Scope: connect:write. { code: hex(64), code_verifier: PKCE string(43..128), redirect_uri: registered URL }. Response: { connection_id: UUID, customer_tenant_id: UUID, customer?: { name: string, email: string } }; profile requires customers:read consent", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "code_verifier": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{43,128}$" }, "redirect_uri": { "type": "string", "format": "uri" } }, "required": [ "code", "code_verifier", "redirect_uri" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "{ connection_id: UUID, customer_tenant_id: UUID, customer?: { name: string, email: string } }; profile requires customers:read consent", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid" }, "customer_tenant_id": { "type": "string", "format": "uuid" }, "customer": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "name", "email" ], "additionalProperties": false } }, "required": [ "connection_id", "customer_tenant_id" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers": { "get": { "summary": "List your active connected customers", "description": "Scope: customers:read. query: cursor?: UUID, limit?: integer(1..100), default 50. Response: { data: Customer[], next_cursor: UUID | null }", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "{ data: Customer[], next_cursor: UUID | null }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers/{id}": { "get": { "summary": "Read your connected customer", "description": "Scope: customers:read. none. Response: { data: Customer }", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: Customer }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers/{id}/connection": { "delete": { "summary": "Disconnect; revoke access and stop sponsorship", "description": "Scope: connect:write. none. Response: { revoked: true }", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ revoked: true }", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "const": true } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customers/{id}/bots": { "get": { "summary": "List that customer’s bots sponsored by you (up to 100)", "description": "Scope: bots:read. none. Response: { data: Bot[] }", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: Bot[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Bot" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a customer-owned bot and reserve one tier slot", "description": "Scope: bots:write. { name: string, plan_tier: starter | growth | scale, language?: string = en }; Idempotency-Key required. Response: { data: { bot_id: UUID, customer_tenant_id: UUID, connection_id: UUID, plan_tier: Tier, funding: vendor, install: { tenantId: UUID, chatbotId: UUID } } }", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9_:.-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BotCreate" } } } }, "responses": { "201": { "description": "{ data: { bot_id: UUID, customer_tenant_id: UUID, connection_id: UUID, plan_tier: Tier, funding: vendor, install: { tenantId: UUID, chatbotId: UUID } } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "bot_id": { "type": "string", "format": "uuid" }, "customer_tenant_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "plan_tier": { "$ref": "#/components/schemas/Tier" }, "funding": { "const": "vendor" }, "install": { "type": "object", "properties": { "tenantId": { "type": "string", "format": "uuid" }, "chatbotId": { "type": "string", "format": "uuid" } }, "required": [ "tenantId", "chatbotId" ], "additionalProperties": false } }, "required": [ "bot_id", "customer_tenant_id", "connection_id", "plan_tier", "funding", "install" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}": { "get": { "summary": "Read a sponsored bot", "description": "Scope: bots:read. none. Response: { data: Bot }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: Bot }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Bot" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit bot name/publication/autosync", "description": "Scope: bots:write. { name?: string, is_active?: boolean, auto_sync_enabled?: boolean }. Response: { data: Bot }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 30 }, "is_active": { "type": "boolean" }, "auto_sync_enabled": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "{ data: Bot }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Bot" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete bot; return its tier slot exactly once", "description": "Scope: bots:write. none. Response: { deleted: UUID }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ deleted: UUID }", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "string", "format": "uuid" } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/deactivate": { "post": { "summary": "Stop sponsored live service; retain slot and data", "description": "Scope: bots:write. none. Response: { ok: true }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ ok: true }", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/reactivate": { "post": { "summary": "Resume with active payment, consent and slot", "description": "Scope: bots:write. none. Response: { ok: true }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ ok: true }", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/plan": { "patch": { "summary": "Change tier atomically; retain used quota", "description": "Scope: bots:write. { plan_tier: Tier }. Response: { ok: true }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_tier": { "$ref": "#/components/schemas/Tier" } }, "required": [ "plan_tier" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "{ ok: true }", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/settings": { "get": { "summary": "Read bot behavior settings", "description": "Scope: bots:read. none. Response: { settings: BotSettings }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ settings: BotSettings }", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/BotSettings" } }, "required": [ "settings" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Save bot behavior settings", "description": "Scope: bots:write. BotSettings (same schema as MonCha bot settings). Response: { settings: BotSettings }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BotSettings" } } } }, "responses": { "200": { "description": "{ settings: BotSettings }", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/BotSettings" } }, "required": [ "settings" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/widget": { "get": { "summary": "Read widget appearance", "description": "Scope: bots:read. none. Response: { config: WidgetConfig }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ config: WidgetConfig }", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/WidgetConfig" } }, "required": [ "config" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Save widget appearance", "description": "Scope: bots:write. WidgetConfig; hideBranding=true is excluded from vendor API purchases and returns branding_locked. Response: { config: WidgetConfig }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetConfig" } } } }, "responses": { "200": { "description": "{ config: WidgetConfig }", "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/WidgetConfig" } }, "required": [ "config" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/domains": { "get": { "summary": "Read allowed embed hostnames", "description": "Scope: bots:read. none. Response: { domains: string[] }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ domains: string[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" } } }, "required": [ "domains" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "summary": "Set allowed embed domains; empty means unrestricted", "description": "Scope: bots:write. { domains: string[0..20] }. Response: { domains: string[] }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string", "maxLength": 253 }, "maxItems": 20 } }, "required": [ "domains" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "{ domains: string[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" } } }, "required": [ "domains" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/install": { "get": { "summary": "Get the CUSTOMER tenant and bot IDs for installation", "description": "Scope: bots:read. none. Response: { tenantId: UUID, chatbotId: UUID, apiUrl: URL, widgetUrl: URL | null }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ tenantId: UUID, chatbotId: UUID, apiUrl: URL, widgetUrl: URL | null }", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenantId": { "type": "string", "format": "uuid" }, "chatbotId": { "type": "string", "format": "uuid" }, "apiUrl": { "type": "string" }, "widgetUrl": { "type": [ "string", "null" ] } }, "required": [ "tenantId", "chatbotId", "apiUrl", "widgetUrl" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/usage": { "get": { "summary": "Read isolated tier usage and funding", "description": "Scope: bots:read. none. Response: { funding: vendor, live: boolean, plan_tier: Tier, limits: Plan, usage: { messages: number, voice_minutes: number, pages: number } }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ funding: vendor, live: boolean, plan_tier: Tier, limits: Plan, usage: { messages: number, voice_minutes: number, pages: number } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "funding": { "const": "vendor" }, "live": { "type": "boolean" }, "plan_tier": { "$ref": "#/components/schemas/Tier" }, "limits": { "$ref": "#/components/schemas/Plan" }, "usage": { "type": "object", "properties": { "messages": { "type": "number" }, "voice_minutes": { "type": "number" }, "pages": { "type": "number" } }, "required": [ "messages", "voice_minutes", "pages" ], "additionalProperties": false } }, "required": [ "funding", "live", "plan_tier", "limits", "usage" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/knowledge/ingest": { "post": { "summary": "Queue one URL/text document", "description": "Scope: kb:write. { documents: [{ title: string(1..300), url?: public URL, text?: string(1..200000), source_type?: url | qa | snippet }] }; exactly one url/text; Idempotency-Key required. Response: { data: { training_id: UUID, status: queued, total: number } }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9_:.-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentInput" }, "minItems": 1, "maxItems": 1 } }, "required": [ "documents" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "{ data: { training_id: UUID, status: queued, total: number } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Training" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/knowledge/ingest-bulk": { "post": { "summary": "Queue up to 100 selected documents", "description": "Scope: kb:write. { documents: DocumentInput[1..100] }; Idempotency-Key required. Response: { data: { training_id: UUID, status: queued, total: number } }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9_:.-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentInput" }, "minItems": 1, "maxItems": 100 } }, "required": [ "documents" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "{ data: { training_id: UUID, status: queued, total: number } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Training" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/knowledge": { "get": { "summary": "List knowledge documents and status", "description": "Scope: kb:read. none. Response: { data: KnowledgeDocument[] }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: KnowledgeDocument[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeDocument" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/training/{trainingId}": { "get": { "summary": "Poll tracked training progress", "description": "Scope: kb:read. none. Response: { training_id: UUID, total: number, ready: number, failed: number, status: processing | completed | partial_failure | failed, documents: KnowledgeDocument[], poll_after_seconds: 5 }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "trainingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ training_id: UUID, total: number, ready: number, failed: number, status: processing | completed | partial_failure | failed, documents: KnowledgeDocument[], poll_after_seconds: 5 }", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Training" } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/knowledge/discover": { "post": { "summary": "Find website pages without starting training", "description": "Scope: kb:write. { url: public URL, max_pages?: integer(1..100)=100, include_paths?: string[0..20], exclude_paths?: string[0..20] }. Response: { urls: URL[], pagesFetched: number, truncated: boolean, next_step: string }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "max_pages": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "include_paths": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20 }, "exclude_paths": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 20 } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "{ urls: URL[], pagesFetched: number, truncated: boolean, next_step: string }", "content": { "application/json": { "schema": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" } }, "pagesFetched": { "type": "number" }, "truncated": { "type": "boolean" }, "next_step": { "type": "string" } }, "required": [ "urls", "pagesFetched", "truncated", "next_step" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/knowledge/upload": { "post": { "summary": "Upload PDF, DOCX, XLSX, XLS, TXT, CSV or Markdown (10 MiB maximum)", "description": "Scope: kb:write. Raw file bytes; X-File-Name: percent-encoded filename; Idempotency-Key required. Response: { data: { training_id: UUID, status: queued, total: number } }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9_:.-]+$" } }, { "name": "X-File-Name", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "maxLength": 10485760 } } } }, "responses": { "202": { "description": "{ data: { training_id: UUID, status: queued, total: number } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Training" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/knowledge/{documentId}": { "get": { "summary": "Read one document, its content and current status", "description": "Scope: kb:read. none. Response: { data: KnowledgeDocument }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: KnowledgeDocument }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KnowledgeDocument" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete one document and return its page usage", "description": "Scope: kb:write. none. Response: { deleted: UUID }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ deleted: UUID }", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "string", "format": "uuid" } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit and retrain a QA/snippet source; queued documents keep their in-progress job", "description": "Scope: kb:write. { title?: string(1..300), text: string(1..200000) }. Response: { data: { training_id: UUID, status: queued | processing, document_id: UUID } }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "text": { "type": "string", "minLength": 1, "maxLength": 200000 } }, "required": [ "text" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "{ data: { training_id: UUID, status: queued | processing, document_id: UUID } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Training" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/knowledge/{documentId}/retrain": { "post": { "summary": "Retrain using the stored source; active jobs are reused", "description": "Scope: kb:write. none. Response: { data: { training_id: UUID, status: queued | processing, document_id: UUID } }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "{ data: { training_id: UUID, status: queued | processing, document_id: UUID } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Training" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/analytics": { "get": { "summary": "Read this bot’s analytics. Bounded results: leads 500, conversations 100, tickets/contacts 300, bookings 200, summaries 12.", "description": "Scope: operations:read. none. Response: { data: analytics[] | object, settings?: object }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: analytics[] | object, settings?: object }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Analytics" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/leads": { "get": { "summary": "Read this bot’s leads. Bounded results: leads 500, conversations 100, tickets/contacts 300, bookings 200, summaries 12.", "description": "Scope: operations:read. none. Response: { data: leads[] | object, settings?: object }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: leads[] | object, settings?: object }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/conversations": { "get": { "summary": "Read this bot’s conversations. Bounded results: leads 500, conversations 100, tickets/contacts 300, bookings 200, summaries 12.", "description": "Scope: operations:read. none. Response: { data: conversations[] | object, settings?: object }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: conversations[] | object, settings?: object }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/tickets": { "get": { "summary": "Read this bot’s tickets. Bounded results: leads 500, conversations 100, tickets/contacts 300, bookings 200, summaries 12.", "description": "Scope: operations:read. none. Response: { data: tickets[] | object, settings?: object }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: tickets[] | object, settings?: object }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/contacts": { "get": { "summary": "Read this bot’s contacts. Bounded results: leads 500, conversations 100, tickets/contacts 300, bookings 200, summaries 12.", "description": "Scope: operations:read. none. Response: { data: contacts[] | object, settings?: object }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: contacts[] | object, settings?: object }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/bookings": { "get": { "summary": "Read this bot’s bookings. Bounded results: leads 500, conversations 100, tickets/contacts 300, bookings 200, summaries 12.", "description": "Scope: operations:read. none. Response: { data: bookings[] | object, settings?: object }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: bookings[] | object, settings?: object }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/summaries": { "get": { "summary": "Read this bot’s summaries. Bounded results: leads 500, conversations 100, tickets/contacts 300, bookings 200, summaries 12.", "description": "Scope: operations:read. none. Response: { data: summaries[] | object, settings?: object }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: summaries[] | object, settings?: object }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Summary" } }, "settings": { "$ref": "#/components/schemas/SummarySettings" } }, "required": [ "data", "settings" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/conversations/{sessionId}": { "get": { "summary": "Read up to 1,000 messages belonging to this bot and session", "description": "Scope: operations:read. none. Response: { data: { id: UUID, role: string, content: string, created_at: ISODate, feedback: string | null }[] }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "{ data: { id: UUID, role: string, content: string, created_at: ISODate, feedback: string | null }[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/inbox": { "get": { "summary": "Read up to 80 existing email inbox threads; does not purchase or enable an inbox", "description": "Scope: operations:read. none. Response: { data: InboxThread[] }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: InboxThread[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InboxThread" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/inbox/{id}": { "get": { "summary": "Read up to 1,000 messages in this bot’s email thread", "description": "Scope: operations:read. none. Response: { data: Message[] }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: Message[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/leads/{id}": { "patch": { "summary": "Edit lead status and notes", "description": "Scope: operations:write. { status?: new | contacted | qualified | won | lost, notes?: string(0..10000) }. Response: { data: Lead }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "new", "contacted", "qualified", "won", "lost" ] }, "notes": { "type": "string", "maxLength": 10000 } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "{ data: Lead }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Lead" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/tickets/{id}/messages": { "get": { "summary": "Read a ticket thread belonging to this bot", "description": "Scope: operations:read. none. Response: { data: TicketMessage[] }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: TicketMessage[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TicketMessage" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Reply as the enterprise support team; visible to the visitor", "description": "Scope: operations:write. { body: string(1..10000) }. Response: { data: TicketMessage }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "body" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "{ data: TicketMessage }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TicketMessage" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/tickets/{id}": { "patch": { "summary": "Update ticket status", "description": "Scope: operations:write. { status: open | in_progress | resolved | closed }. Response: { data: Ticket }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "in_progress", "resolved", "closed" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "{ data: Ticket }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/bookings/{id}": { "patch": { "summary": "Confirm/reject/reschedule/cancel using MonCha booking rules; vendor handles its own customer notifications", "description": "Scope: operations:write. { action: confirm | reject | reschedule | cancel, requestedSlot?: ISODate, rejectionComment?: string(0..1000), cancelComment?: string(0..1000) }. Response: { data: Booking }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "confirm", "reject", "reschedule", "cancel" ] }, "requestedSlot": { "type": "string", "format": "date-time" }, "rejectionComment": { "type": "string", "maxLength": 1000 }, "cancelComment": { "type": "string", "maxLength": 1000 } }, "required": [ "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "{ data: Booking }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Booking" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/summaries/settings": { "patch": { "summary": "Set the bot’s summary cadence", "description": "Scope: operations:write. { interval_days: 30 | 90 }. Response: { ok: true }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "interval_days": { "type": "integer", "enum": [ 30, 90 ] } }, "required": [ "interval_days" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "{ ok: true }", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/notifications": { "put": { "summary": "Set bot notification destinations; vendor overrides clear on disconnect/takeover", "description": "Scope: bots:write. { notify_email: email | null, ticket_alert_emails: email[0..10] }. Response: { ok: true }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "notify_email": { "type": [ "string", "null" ], "format": "email" }, "ticket_alert_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 10 } }, "required": [ "notify_email", "ticket_alert_emails" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "{ ok: true }", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/functions": { "get": { "summary": "List only functions created through this vendor connection; secrets are omitted", "description": "Scope: integrations:manage. none. Response: { data: Function[] }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: Function[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Function" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a bot-only function, subject to tier and enterprise API entitlement", "description": "Scope: integrations:manage. { name: lowercase identifier(2..61), description: string(10..500), method: GET | POST, url: HTTPS URL, headers?: Record, params: Record }. Response: { data: Function }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,60}$" }, "description": { "type": "string", "minLength": 10, "maxLength": 500 }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "url": { "type": "string", "format": "uri", "maxLength": 2000 }, "headers": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 } }, "params": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 300 } } }, "required": [ "name", "description", "method", "url", "params" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "{ data: Function }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Function" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/functions/{id}": { "delete": { "summary": "Delete a vendor-owned functions resource", "description": "Scope: integrations:manage. none. Response: { deleted: UUID }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ deleted: UUID }", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "string", "format": "uuid" } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/webhooks": { "get": { "summary": "List only webhooks created through this vendor connection; secrets are omitted", "description": "Scope: integrations:manage. none. Response: { data: Webhook[] }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: Webhook[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a bot-only webhook; the signing secret is shown once; requires tier and contract webhooks", "description": "Scope: integrations:manage. { url: HTTPS URL, events: (lead.created | conversation.handoff | message.unanswered | ticket.created | booking.created)[] }. Response: { data: Webhook & { secret: string } }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "lead.created", "conversation.handoff", "message.unanswered", "ticket.created", "booking.created" ] }, "minItems": 1 } }, "required": [ "url", "events" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "{ data: Webhook & { secret: string } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/webhooks/{id}": { "delete": { "summary": "Delete a vendor-owned webhooks resource", "description": "Scope: integrations:manage. none. Response: { deleted: UUID }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ deleted: UUID }", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "string", "format": "uuid" } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/integrations/{provider}/authorize": { "post": { "summary": "Start separate provider consent for notion or google; never uses customer-wide connections", "description": "Scope: integrations:manage. { redirect_uri: registered URL, state: string(32..256) }. Response: { authorization_url: URL, expires_in: 600 }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "notion", "google" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_uri": { "type": "string", "format": "uri" }, "state": { "type": "string", "minLength": 32, "maxLength": 256 } }, "required": [ "redirect_uri", "state" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "{ authorization_url: URL, expires_in: 600 }", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorization_url": { "type": "string" }, "expires_in": { "type": "integer" } }, "required": [ "authorization_url", "expires_in" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/integrations/{provider}": { "get": { "summary": "List pages/files available through this bot/vendor’s provider grant", "description": "Scope: integrations:manage. none. Response: { data: { id: string, title: string, url?: URL, mimeType?: string }[] }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "notion", "google" ] } } ], "responses": { "200": { "description": "{ data: { id: string, title: string, url?: URL, mimeType?: string }[] }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete this scoped provider grant; imported documents are retained", "description": "Scope: integrations:manage. none. Response: { disconnected: true }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "notion", "google" ] } } ], "responses": { "200": { "description": "{ disconnected: true }", "content": { "application/json": { "schema": { "type": "object", "properties": { "disconnected": { "const": true } }, "required": [ "disconnected" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/integrations/{provider}/import": { "post": { "summary": "Import up to 20 selected pages/files as editable text snapshots", "description": "Scope: integrations:manage + kb:write. { items: { id: string, title: string(1..300), mime_type?: string }[1..20] }; Idempotency-Key required. Response: { data: { training_id: UUID, status: queued, total: number } }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "notion", "google" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9_:.-]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,200}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "mime_type": { "type": "string", "maxLength": 120 } }, "required": [ "id", "title" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20 } }, "required": [ "items" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "{ data: { training_id: UUID, status: queued, total: number } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Training" } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/channels/whatsapp": { "get": { "summary": "Read this vendor’s bring-your-own WhatsApp connection", "description": "Scope: integrations:manage. none. Response: { data: Channel | null }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: Channel | null }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/Channel" }, { "type": "null" } ] } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Configure the vendor-owned channel", "description": "Scope: integrations:manage. { aiEnabled?: boolean, showOnWidget?: boolean }. Response: { ok: true }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "aiEnabled": { "type": "boolean" }, "showOnWidget": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "{ ok: true }", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Disconnect the vendor-owned channel", "description": "Scope: integrations:manage. none. Response: { disconnected: true }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ disconnected: true }", "content": { "application/json": { "schema": { "type": "object", "properties": { "disconnected": { "const": true } }, "required": [ "disconnected" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/channels/whatsapp/connect": { "post": { "summary": "Start provider-hosted connection in a dedicated bot profile; does not buy numbers", "description": "Scope: integrations:manage. { redirect_uri: registered URL }. Response: { authorization_url: URL }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_uri": { "type": "string", "format": "uri" } }, "required": [ "redirect_uri" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "{ authorization_url: URL }", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorization_url": { "type": "string" } }, "required": [ "authorization_url" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bots/{botId}/channels/whatsapp/complete": { "post": { "summary": "Complete after provider consent; retry 409 connect_incomplete after five seconds", "description": "Scope: integrations:manage. none. Response: { data: { id: UUID, status: active, phone_number: string | null } }", "parameters": [ { "name": "botId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "{ data: { id: UUID, status: active, phone_number: string | null } }", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "active" }, "phone_number": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "phone_number" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Read Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See error.code; do not retry unchanged 4xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }