{"openapi":"3.1.0","info":{"title":"Knowvo API","version":"1.0.0","description":"API for chatting with chatbots and registering leads."},"servers":[{"url":"https://knowvoai.com/api/v1"}],"tags":[{"name":"Chat","description":"Conversations with published chatbots."},{"name":"Leads","description":"Consent-based contact capture."}],"paths":{"/chat":{"post":{"operationId":"sendChatMessage","summary":"Send a message","tags":["Chat"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chatbotId","message"],"properties":{"chatbotId":{"type":"string","minLength":1},"message":{"type":"string","maxLength":4000},"conversationId":{"type":"string"},"locale":{"type":"string","enum":["es","en"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Response, conversation, metrics, and citations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"description":"The LLM provider could not respond."}}}},"/leads":{"post":{"operationId":"createLead","summary":"Register a lead with consent","tags":["Leads"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chatbotId","email","consent"],"properties":{"chatbotId":{"type":"string","minLength":1},"conversationId":{"type":"string"},"name":{"type":"string","maxLength":120},"email":{"type":"string","format":"email","maxLength":320},"phone":{"type":"string","maxLength":40},"consent":{"type":"boolean","const":true}},"additionalProperties":false}}}},"responses":{"201":{"description":"Lead created."},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"nx_live_...","description":"API token with the required scope."}},"schemas":{"ChatResponse":{"type":"object","required":["conversationId","answer"],"properties":{"conversationId":{"type":"string"},"answer":{"type":"string"},"citations":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"latencyMs":{"type":"integer","minimum":0},"estimatedTokens":{"type":"integer","minimum":0}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"InvalidRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Token missing, invalid, revoked, or missing scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Usage limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}