{"openapi":"3.1.0","info":{"title":"MagicChat API","version":"1.0.0","summary":"Ask a MagicChat chatbot a question and get an answer grounded in the content it was trained on.","description":"MagicChat trains a chatbot on your website, help center, PDFs and YouTube videos. The public API lets any client — a Zapier/Make zap, an AI agent, a CLI — ask a specific bot a question and receive the grounded answer the widget would give.\n\nNo API key is required: a bot is addressed by its public `bot_id` (the same value in its embed snippet). Treat the bot_id as the credential — only expose bots whose knowledge is meant to be public.\n\nTypical latency is 2–8 seconds (embedding + retrieval + LLM).\n\nHuman docs: https://magicchat.ai/docs · CLI for agents: https://magicchat.ai/docs/cli · Site overview for LLMs: https://magicchat.ai/llms.txt","termsOfService":"https://magicchat.ai/terms","contact":{"name":"MagicChat Support","email":"support@magicchat.ai","url":"https://magicchat.ai/contact"}},"externalDocs":{"description":"MagicChat documentation","url":"https://magicchat.ai/docs"},"servers":[{"url":"https://magicchat.ai","description":"MagicChat production"}],"tags":[{"name":"Chat","description":"Ask a trained chatbot a question."}],"paths":{"/api/public/ask-ai-query":{"post":{"operationId":"askBot","tags":["Chat"],"summary":"Ask a chatbot a question","description":"Embeds the question, retrieves the most relevant chunks from the bot's indexed content (hybrid vector + keyword search) and answers with an LLM grounded in that context. Returns the answer text. If the bot has no relevant content the model answers without grounding.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bot_id","query"],"properties":{"bot_id":{"type":"string","description":"Public ID of the bot, as found in its embed snippet or the dashboard.","example":"bot_abc123"},"query":{"type":"string","description":"The question to ask, in any language.","example":"What is your refund policy?"}}},"examples":{"basic":{"summary":"Ask a support question","value":{"bot_id":"bot_abc123","query":"Do you offer a free trial?"}}}}}},"responses":{"200":{"description":"Answer generated.","content":{"application/json":{"schema":{"type":"object","required":["answer"],"properties":{"answer":{"type":"string","description":"The chatbot's answer, plain text / light markdown."},"contextString":{"type":"string","description":"Concatenated retrieved context the answer was grounded in. Empty when nothing relevant was indexed."},"prompt":{"type":"string","description":"The final prompt sent to the model (for debugging)."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"string","description":"Human-readable message."},"code":{"type":"string","enum":["INVALID_BOT_ID","INVALID_JSON","NOT_FOUND","SERVER_ERROR"]}}}},"responses":{"BadRequest":{"description":"Missing or unknown bot_id, missing query, or malformed JSON body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid bot_id"}}}},"NotFound":{"description":"No such API route. Body lists the valid endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Answer generation failed. Safe to retry once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Failed to process query"}}}}}}}