{"openapi":"3.1.0","info":{"title":"Bolrach Bots API","version":"1.0.0","description":"The public surface of the bot.ng engine: browse bot templates and the public-bot directory, read a bot's public card, and hold web-chat conversations with live public bots. Reads need `bots:read`; chatting needs `bots:run`.","contact":{"url":"https://docs.bolrach.com/bots"}},"servers":[{"url":"https://api.bolrach.com"}],"security":[{"bearerKey":[]},{"headerKey":[]}],"paths":{"/v1/bots/templates":{"get":{"operationId":"botsTemplates","summary":"List bot templates","responses":{"200":{"description":"Template gallery (key, name, category, description)."},"400":{"description":"Bad input (`bad_request`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `bots:read` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"404":{"description":"No such bot/template, or the bot is not public and live.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}},"/v1/bots/templates/{key}":{"get":{"operationId":"botsTemplate","summary":"One template in detail","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"},"example":"faq"}],"responses":{"200":{"description":"The template with its flow definition."},"400":{"description":"Bad input (`bad_request`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `bots:read` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"404":{"description":"No such bot/template, or the bot is not public and live.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}},"/v1/bots/directory":{"get":{"operationId":"botsDirectory","summary":"Browse public bots","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Public, live bots."},"400":{"description":"Bad input (`bad_request`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `bots:read` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"404":{"description":"No such bot/template, or the bot is not public and live.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}},"/v1/bots/{slug}":{"get":{"operationId":"botsCard","summary":"A bot's public card","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Name, handle, description, category."},"400":{"description":"Bad input (`bad_request`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `bots:read` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"404":{"description":"No such bot/template, or the bot is not public and live.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}},"/v1/bots/{botId}/chat":{"post":{"operationId":"botsChat","summary":"Send a message to a live public bot","description":"Web-chat with a public bot. Keep the returned `visitorId` and pass it back as `sessionKey` to continue the same conversation.","parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":4000},"sessionKey":{"type":"string","description":"Continue an existing conversation."},"visitorId":{"type":"string","description":"Your own stable id for the end user."}},"required":["text"]},"example":{"text":"What are your opening hours?"}}}},"responses":{"200":{"description":"The bot's replies for this turn.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"sessionId":{"type":"string"},"visitorId":{"type":"string","description":"Echo of (or a generated) end-user id — reuse as sessionKey."},"replies":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Bad input (`bad_request`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `bots:run` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"404":{"description":"No such bot/template, or the bot is not public and live.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}},"/v1/bots/{botId}/messages":{"get":{"operationId":"botsMessages","summary":"Poll a conversation for new messages","description":"Returns the session's messages after a timestamp — how agent replies and async bot messages reach your end user.","parameters":[{"name":"botId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"sessionKey","in":"query","required":true,"schema":{"type":"string"},"description":"The visitorId/sessionKey used in /chat."},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Session status and new messages.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":["string","null"]},"handling":{"type":["string","null"]},"messages":{"type":"array","items":{"type":"object","properties":{"direction":{"type":"string"},"body":{"type":"string"},"created_at":{"type":"string"}}}}}}}}},"400":{"description":"Bad input (`bad_request`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `bots:run` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"404":{"description":"No such bot/template, or the bot is not public and live.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}}},"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer bt_..."},"headerKey":{"type":"apiKey","in":"header","name":"x-api-key"}}}}