{"openapi":"3.1.0","info":{"title":"Helovo Chatbot API","version":"1.0.0","description":"Send messages to a Helovo chatbot from your own server and get its answers. The chatbot's knowledge, tone and rules are managed in the Helovo dashboard. Server-to-server only: browser (CORS) requests are refused.","contact":{"email":"iletisim@ragzeka.com","url":"https://helovo.com/en/developers"},"termsOfService":"https://helovo.com/en/terms"},"externalDocs":{"url":"https://helovo.com/en/developers","description":"Developer guide"},"servers":[{"url":"https://api.helovo.com/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/chat":{"post":{"operationId":"chat","summary":"Send a message and get the chatbot's answer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bot_id","message"],"properties":{"bot_id":{"type":"string","description":"The chatbot's ID (bot_…), shown on its Install tab.","examples":["bot_01J…"]},"message":{"type":"string","maxLength":4000,"description":"The user's message."},"conversation_id":{"type":"string","description":"Continue an existing conversation. Omit to start a new one."},"user":{"type":"string","maxLength":128,"description":"Your own ID for the end user; shown in the dashboard."},"stream":{"type":"boolean","default":false,"description":"Stream the answer as Server-Sent Events: meta → delta… → done, or error."}}}}}},"responses":{"200":{"description":"The answer. With stream=true, a text/event-stream instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}},"text/event-stream":{"schema":{"type":"string","description":"Events: meta {conversation_id, message_id}, delta {text}, done, error {code, message}."}}}},"400":{"description":"Invalid JSON or an unknown field (invalid_request).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Chatbot or conversation not found, or not accessible with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The chatbot is paused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The message is empty or too long.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit (per minute) or monthly quota reached. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The assistant couldn't answer (ai_error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The assistant is not available (ai_not_configured).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The assistant timed out (ai_timeout).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/chatbots":{"get":{"operationId":"listChatbots","summary":"List the chatbots this key can use","responses":{"200":{"description":"Chatbots","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Chatbot"}}}}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations/{id}":{"get":{"operationId":"getConversation","summary":"Get the messages of a conversation started through the API","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Conversation not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Workspace API key (sk_…), created in the dashboard."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["invalid_api_key"]},"message":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message"]}}},"ChatResponse":{"type":"object","properties":{"id":{"type":"string","description":"The answer's message ID."},"conversation_id":{"type":"string"},"answer":{"type":"string"},"model":{"type":"string","enum":["standard","advanced"]},"finish_reason":{"type":"string"},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"}}}}},"Chatbot":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}},"Conversation":{"type":"object","properties":{"id":{"type":"string"},"bot_id":{"type":"string"},"user":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}}}}}