{"openapi":"3.1.0","info":{"title":"Botnest Public API","version":"1.1.0","description":"Tenant-scoped read API for Botnest integrations. All protected operations require a scoped organization API key."},"servers":[{"url":"/public/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/bots":{"get":{"operationId":"listBots","summary":"List bots","tags":["Bots"],"responses":{"200":{"$ref":"#/components/responses/BotList"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/subscribers":{"get":{"operationId":"listSubscribers","summary":"List subscribers","tags":["CRM"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"botId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","schema":{"type":"string","maxLength":120}},{"name":"status","in":"query","schema":{"type":"string","enum":["active","blocked"]}}],"responses":{"200":{"$ref":"#/components/responses/SubscriberList"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/deliveries":{"get":{"operationId":"listDeliveries","summary":"List delivery outcomes","description":"Returns operational metadata without chat IDs, Telegram message IDs or message text.","tags":["Delivery"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"botId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","sent","failed","cancelled"]}},{"name":"errorCategory","in":"query","schema":{"type":"string","enum":["telegram","network","timeout","storage","configuration","policy","unknown"]}}],"responses":{"200":{"$ref":"#/components/responses/DeliveryList"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/analytics/overview":{"get":{"operationId":"getAnalyticsOverview","summary":"Read aggregate product analytics","tags":["Analytics"],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","enum":[7,30,90],"default":30}},{"name":"botId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"scenarioId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"$ref":"#/components/responses/AnalyticsOverview"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","summary":"Download this OpenAPI contract","security":[],"tags":["Contract"],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"bc_live_ organization API key"}},"parameters":{"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}},"Cursor":{"name":"cursor","in":"query","description":"Opaque cursor returned by the previous page","schema":{"type":"string"}}},"schemas":{"Bot":{"type":"object","required":["id","name","status","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"telegramUsername":{"type":["string","null"]},"status":{"type":"string"},"activatedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"Subscriber":{"type":"object","description":"Minimized CRM projection. Chat IDs and raw Telegram data are excluded.","properties":{"id":{"type":"string","format":"uuid"},"botId":{"type":"string","format":"uuid"},"botName":{"type":"string"},"telegramUserId":{"type":"string"},"username":{"type":["string","null"]},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"languageCode":{"type":["string","null"]},"timezone":{"type":["string","null"]},"isBlocked":{"type":"boolean"},"firstSeenAt":{"type":"string","format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"},"messageCount":{"type":"integer"},"marketingConsent":{"type":"string"},"acquisitionSource":{"type":["object","null"]},"tags":{"type":"array","items":{"type":"object"}},"customFields":{"type":"array","items":{"type":"object"}}}},"Delivery":{"type":"object","description":"Safe operational projection without recipient or content identifiers.","properties":{"id":{"type":"string","format":"uuid"},"botId":{"type":"string","format":"uuid"},"botName":{"type":"string"},"status":{"type":"string"},"attempts":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"sentAt":{"type":["string","null"],"format":"date-time"},"failedAt":{"type":["string","null"],"format":"date-time"},"errorCode":{"type":["string","null"]},"errorCategory":{"type":["string","null"]},"retryable":{"type":["boolean","null"]},"retryRequestedAt":{"type":["string","null"],"format":"date-time"},"action":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"mediaCount":{"type":"integer"}}}}},"Page":{"type":"object","properties":{"data":{"type":"array","items":{}},"nextCursor":{"type":["string","null"]}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"BotList":{"description":"Bots","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Bot"}}}}}}},"SubscriberList":{"description":"Subscriber page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"DeliveryList":{"description":"Delivery page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"AnalyticsOverview":{"description":"Aggregate analytics overview","content":{"application/json":{"schema":{"type":"object"}}}},"Unauthorized":{"description":"Missing, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}