{"openapi":"3.1.0","info":{"title":"SupportAi Public API","version":"1.0.0","description":"Programmatic access to your SupportAi workspace: send messages to your agents, read conversations and leads, and manage knowledge sources. Authenticate with a workspace API key created under **Settings → API keys**.","contact":{"name":"SupportAi","url":"https://app.supportai.co.uk"}},"servers":[{"url":"https://app.supportai.co.uk/api/public/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Chatbots","description":"List the agents in your workspace."},{"name":"Chat","description":"Send messages and receive replies (JSON or Server-Sent Events)."},{"name":"Conversations","description":"Read conversation history from every channel."},{"name":"Leads","description":"Leads captured by forms, email capture or the `capture_lead` tool."},{"name":"Sources","description":"Manage knowledge sources and trigger reindexing."}],"paths":{"/chatbots":{"get":{"tags":["Chatbots"],"summary":"List chatbots","operationId":"listChatbots","x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Chatbot"}},"nextCursor":{"type":["integer","null"],"description":"Pass as `cursor` to fetch the next page."}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope or the plan does not include API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chatbots/{botId}":{"get":{"tags":["Chatbots"],"summary":"Get a chatbot","operationId":"getChatbot","x-scope":"read","parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Chatbot ID (UUID shown in the dashboard)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Chatbot"}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope or the plan does not include API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chatbots/{botId}/chat":{"post":{"tags":["Chat"],"summary":"Send a message","operationId":"chat","x-scope":"chat","description":"Sends a visitor message to the agent and returns the reply. Omit `conversationId` to start a new conversation (optionally keyed by your own `visitorId`), or pass one to continue an existing thread. Set `stream: true` or send `Accept: text/event-stream` to receive Server-Sent Events: `start`, `delta`, `tool`, `widget`, `done`. Each call consumes message credits from the workspace plan.","parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Chatbot ID (UUID shown in the dashboard)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}},"responses":{"200":{"description":"Reply","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChatResponse"}}}},"text/event-stream":{"schema":{"type":"string","description":"SSE stream. `delta` events carry `{ text }`; the final `done` event carries a ChatResponse."}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope missing, or message credits exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Chatbot or conversation not found"},"429":{"description":"Rate limit exceeded (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations":{"get":{"tags":["Conversations"],"summary":"List conversations","operationId":"listConversations","x-scope":"read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"integer"},"description":"Return items with an id lower than this value."},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"chatbotId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","enum":["new","open","pending","closed"]}},{"name":"channel","in":"query","schema":{"type":"string"},"description":"e.g. `web`, `api`"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"nextCursor":{"type":["integer","null"],"description":"Pass as `cursor` to fetch the next page."}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope or the plan does not include API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{conversationId}":{"get":{"tags":["Conversations"],"summary":"Get a conversation with messages","operationId":"getConversation","x-scope":"read","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Conversation"},{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}}]}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope or the plan does not include API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads":{"get":{"tags":["Leads"],"summary":"List leads","operationId":"listLeads","x-scope":"read","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"integer"},"description":"Return items with an id lower than this value."},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"chatbotId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"nextCursor":{"type":["integer","null"],"description":"Pass as `cursor` to fetch the next page."}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope or the plan does not include API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chatbots/{botId}/sources":{"get":{"tags":["Sources"],"summary":"Summarise knowledge sources","operationId":"getSources","x-scope":"read","parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Chatbot ID (UUID shown in the dashboard)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Sources"}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope or the plan does not include API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chatbots/{botId}/sources/qa":{"post":{"tags":["Sources"],"summary":"Add Q&A pairs","operationId":"addQa","x-scope":"write","parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Chatbot ID (UUID shown in the dashboard)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","maxItems":200,"items":{"type":"object","required":["question","answer"],"properties":{"question":{"type":"string"},"answer":{"type":"string"}}}},"reindex":{"type":"boolean","default":true}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/QaItem"}},"nextCursor":{"type":["integer","null"],"description":"Pass as `cursor` to fetch the next page."}}}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope or the plan does not include API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chatbots/{botId}/sources/qa/{qaId}":{"delete":{"tags":["Sources"],"summary":"Delete a Q&A pair","operationId":"deleteQa","x-scope":"write","parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Chatbot ID (UUID shown in the dashboard)."},{"name":"qaId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope or the plan does not include API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found"},"429":{"description":"Rate limit exceeded (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chatbots/{botId}/sources/text":{"put":{"tags":["Sources"],"summary":"Replace or append training text","operationId":"putText","x-scope":"write","parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Chatbot ID (UUID shown in the dashboard)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string"},"mode":{"type":"string","enum":["replace","append"],"default":"replace"}}}}}},"responses":{"200":{"description":"Saved and reindex queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"characters":{"type":"integer"},"reindexQueued":{"type":"boolean"}}}}}}}},"400":{"description":"Exceeds plan character limit"},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope or the plan does not include API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chatbots/{botId}/reindex":{"post":{"tags":["Sources"],"summary":"Queue a full reindex","operationId":"reindex","x-scope":"write","parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Chatbot ID (UUID shown in the dashboard)."}],"responses":{"202":{"description":"Queued"},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope or the plan does not include API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (120 requests/minute per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"sk_live_…","description":"Workspace API key. Scopes: read, write, chat."}},"schemas":{"Error":{"type":"object","properties":{"status":{"type":"integer"},"message":{"type":"string"},"code":{"type":"string"}}},"Chatbot":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"model":{"type":"string"},"indexStatus":{"type":"string","enum":["idle","queued","indexing","ready","error"]},"indexedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"ChatRequest":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":4000},"conversationId":{"type":"integer","description":"Continue an existing conversation."},"visitorId":{"type":"string","description":"Your identifier for the end user; used to group new conversations."},"metadata":{"type":"object","additionalProperties":true},"stream":{"type":"boolean","default":false}}},"ChatResponse":{"type":"object","properties":{"conversationId":{"type":"integer"},"messageId":{"type":["integer","null"]},"reply":{"type":["string","null"]},"widget":{"type":["object","null"],"description":"Rich widget the agent chose to display (card, buttons, quickReplies, link, image, keyValue, form)."},"escalated":{"type":["string","null"],"description":"Reason the agent escalated to a human, if it did."},"handedOff":{"type":"boolean","description":"True when a human has taken over and the AI did not reply."},"model":{"type":"string"},"toolCalls":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"ok":{"type":"boolean"}}}}}},"Conversation":{"type":"object","properties":{"id":{"type":"integer"},"chatbotUuid":{"type":"string","format":"uuid"},"chatbotName":{"type":["string","null"]},"status":{"type":"string","enum":["new","open","pending","closed"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"channel":{"type":"string"},"email":{"type":["string","null"]},"topic":{"type":["string","null"]},"resolved":{"type":["boolean","null"]},"aiPaused":{"type":"boolean"},"assigneeId":{"type":["integer","null"]},"escalatedAt":{"type":["string","null"],"format":"date-time"},"lastMessageAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"Message":{"type":"object","properties":{"id":{"type":"integer"},"conversationId":{"type":"integer"},"sender":{"type":"string","enum":["user","assistant","agent","system"]},"message":{"type":"string"},"widget":{"type":["object","null"]},"timestamp":{"type":"string","format":"date-time"}}},"Lead":{"type":"object","properties":{"id":{"type":"integer"},"chatbotId":{"type":"string","format":"uuid"},"conversationId":{"type":["integer","null"]},"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"fields":{"type":["object","null"],"additionalProperties":true},"source":{"type":"string","enum":["form","email_capture","tool"]},"createdAt":{"type":"string","format":"date-time"}}},"QaItem":{"type":"object","properties":{"id":{"type":"integer"},"question":{"type":"string"},"answer":{"type":"string"}}},"Sources":{"type":"object","properties":{"text":{"type":"object","properties":{"characters":{"type":"integer"}}},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"characters":{"type":"integer"}}}},"qa":{"type":"array","items":{"$ref":"#/components/schemas/QaItem"}},"indexStatus":{"type":"string"},"indexedAt":{"type":["string","null"],"format":"date-time"}}},"WebhookEvent":{"type":"object","description":"Payload POSTed to your webhook endpoints. Verify the `X-SupportAi-Signature` header (`t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" using your endpoint secret>`).","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["conversation.created","conversation.closed","message.created","lead.created","escalation.created","action.failed"]},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true}}}}}}