{"openapi":"3.0.3","info":{"title":"TeleBotHost Developer API Reference","description":"\nWelcome to the TeleBotHost Developer API reference. \n\nThis reference documents bot hosting, community store, and **public discovery** endpoints.\n\n**Authenticated routes** (`/bot`, `/store`) work with Developer API Keys (`sk_*` for write access, `pub_*` for read-only access).\n\n**Public routes** (`/public/*`) require no authentication — use them for profiles, public bot browsing, templates, and store discovery.\n\n---\n\n### Authentication Guide\n\nTo programmatically authenticate your server-to-server requests, choose one of the following methods:\n\n1. **Bearer Token (Recommended)**:\n   Add the HTTP header:\n   ```http\n   Authorization: Bearer sk_your_secret_key_here\n   ```\n   \n2. **Custom API Key Header**:\n   Add the HTTP header:\n   ```http\n   X-Api-Key: sk_your_secret_key_here\n   ```\n\n> **Security Warning**: Keep your Secret Key (sk_*) private. Never expose it in client-side code, mobile applications, or public repositories. For client-side or read-only public panels, use your Public Key (pub_*).\n\n---\n\n### Quota and Rate Limits\n\nDeveloper API requests are rate-limited based on your active plan tier:\n\n| Plan Tier | Daily Request Limit | Per-Minute Rate Limit | Monthly Request Limit |\n|---|---|---|---|\n| **FREE / FREEMIUM** | 1,000 requests / day | 15 requests / min | 15,000 requests / month |\n| **PREMIUM** | 5,000 requests / day | 60 requests / min | 75,000 requests / month |\n| **ELITE** | 10,000 requests / day | 120 requests / min | 150,000 requests / month |\n\n*Public keys (pub_*) are capped at a maximum of 1,000 requests per day, 15 requests per minute, and 15,000 requests per month, regardless of the plan.*\n\n#### API Strike and Account Restriction System\nBreaching the per-minute limit repeatedly will trigger strikes on your developer key:\n- **3 Strikes**: An automated safety warning email is dispatched to your account.\n- **5 Strikes**: Instead of an immediate ban, your account status is set to **limited**. While limited, request rate limits are progressively restricted (reduced 2x, 4x, 6x, 8x with each violation).\n- **Repeated Violations**: If you violate limits 5 times while in limited status:\n  - On the first cycle, you receive a **1-day temporary ban**.\n  - Subsequent bans after unbanning result in a **permanent ban** of the account.\n\n#### Quota Tracking Headers\nEvery authenticated API response returns headers to track your daily, per-minute, and monthly usage:\n- `X-RateLimit-Limit`: Your daily quota ceiling.\n- `X-RateLimit-Remaining`: Remaining requests left for today.\n- `X-RateLimit-Reset`: Unix timestamp when the daily limit resets (UTC midnight).\n- `X-RateLimit-Limit-Minute`: Per-minute rate ceiling.\n- `X-RateLimit-Remaining-Minute`: Remaining requests left for the current minute window.\n- `X-RateLimit-Reset-Minute`: Unix timestamp when the current minute resets.\n- `X-RateLimit-Limit-Month`: Your monthly quota ceiling.\n- `X-RateLimit-Remaining-Month`: Remaining requests left for the current calendar month.\n- `X-RateLimit-Reset-Month`: Unix timestamp when the monthly limit resets.\n\n#### Bot Creation and Capacity Limits\nThe following creation rate limits, capacities, and size restrictions are enforced across all plans:\n- **Creation Frequency Rate Limits**:\n  - Command, Environment Variable, and Folder Creations: 10 creations/sec, 30 creations/min, 200 creations/hr.\n  - Bot Cloning and Store Installations: 1 clone/sec, 5 clones/min, 20 clones/hr.\n- **Bot Document Capacity Caps**:\n  - Maximum Commands per Bot: 1000\n  - Maximum Environment Variables per Bot: 100\n  - Maximum Command Folders per Bot: 50\n- **Total Payload Caps**:\n  - Total Command payload per Bot: Max 10MB (combined code, answer, keyboard, aliases, etc.)\n  - Total Environment payload per Bot: Max 1MB (combined name, value, placeholder)\n- **Size Caps**:\n  - Individual Command Code / Script size: Max 100,000 characters (~100KB).\n  - Individual Command Answer: Max 10,000 characters (~10KB).\n  - Individual Env Variable Value: Max 10,000 characters (~10KB).\n","version":"1.0.0"},"servers":[{"url":"https://api.telebothost.com/api/v1","description":"Default relative path for current host"}],"components":{"securitySchemes":{"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Developer API key."},"bearerAuth":{"type":"http","scheme":"bearer","description":"Developer API key or session token."}},"schemas":{"Ad":{"type":"object","properties":{"id":{"type":"string","example":"665a1b2c3d4e5f6789012345"},"position":{"type":"string","example":"side-menu"},"title":{"type":"string","example":"New Ad Title"},"description":{"type":"string","example":"Ad Description","nullable":true},"buttonText":{"type":"string","example":"Click Here","nullable":true},"url":{"type":"string","example":"https://example.com"},"icon":{"type":"string","example":"fas fa-rectangle-ad","nullable":true},"imageUrl":{"type":"string","example":"https://example.com/ad.png","nullable":true},"isActive":{"type":"boolean","example":true},"expiresAt":{"type":"string","format":"date-time","example":"2027-01-01T00:00:00.000Z","nullable":true}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"reason":{"type":"string","example":"invalid_input","nullable":true},"message":{"type":"string","example":"Error description"},"errors":{"type":"object","description":"Validation errors grouped by field","nullable":true}}},"UserProfile":{"type":"object","properties":{"fullname":{"type":"string","example":"John Doe"},"username":{"type":"string","example":"johndoe123"},"location":{"type":"string","example":"San Francisco, CA"},"bio":{"type":"string","example":"Developer","nullable":true},"avatar":{"type":"string","example":"https://example.com/avatar.jpg"}}},"User":{"type":"object","properties":{"id":{"type":"string","example":"60c72b2f9b1d8a25c8d23456"},"mail":{"type":"string","example":"john@example.com"},"profile":{"$ref":"#/components/schemas/UserProfile"},"role":{"type":"string","example":"user"},"created_at":{"type":"string","format":"date-time","example":"2026-06-18T09:30:00.000Z"}}},"Bot":{"type":"object","properties":{"bot_id":{"type":"integer","example":123456},"bot_token":{"type":"string","example":"123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ","nullable":true},"bot_id_token":{"type":"string","example":"123456789","nullable":true},"bot_username":{"type":"string","example":"my_telegram_bot"},"bot_name":{"type":"string","example":"My Telegram Bot"},"owner":{"type":"string","example":"owner@example.com"},"owner_id":{"type":"string","example":"60c72b2f9b1d8b3d88888888"},"status":{"type":"integer","example":1},"blocked":{"type":"integer","example":0},"pin":{"type":"boolean","example":false},"is_cloned":{"type":"integer","example":0},"is_transferred":{"type":"integer","example":0},"is_public_store":{"type":"integer","example":0},"is_template":{"type":"integer","example":0},"bot_photo":{"type":"string","example":"https://ui-avatars.com/api/?name=M&background=random"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_started":{"type":"string","format":"date-time","nullable":true},"last_used":{"type":"string","format":"date-time","nullable":true},"tbl_var":{"type":"string","example":"1.0.0"},"commands_count":{"type":"integer","example":4},"uptime":{"type":"string","example":"1d 4h 12m","nullable":true}}},"BotListItem":{"type":"object","properties":{"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"My Telegram Bot"},"photo":{"type":"string","example":"https://t.me/i/userpic/320/my_telegram_bot.jpg"},"is_transferred":{"type":"integer","example":0},"is_cloned":{"type":"integer","example":0},"is_public_store":{"type":"integer","example":0},"is_template":{"type":"integer","example":0},"tbl_var":{"type":"string","example":"1.0.0","nullable":true},"bot_username":{"type":"string","example":"my_telegram_bot"},"status":{"type":"integer","example":1},"pin":{"type":"boolean","example":false},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"blocked":{"type":"integer","example":0},"uptime":{"type":"string","example":"1d 4h 12m","nullable":true},"commands_count":{"type":"integer","example":4}}},"Command":{"type":"object","properties":{"id":{"type":"integer","example":1},"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"/start"},"code":{"type":"string","example":"ctx.reply(\"Hello!\");"},"answer":{"type":"string","example":"Welcome message"},"parse_mode":{"type":"string","example":"Markdown"},"keyboard":{"type":"string","example":"main_menu"},"aliases":{"type":"array","items":{"type":"string"},"example":["begin","help"]},"allow_only_group":{"type":"boolean","example":false},"need_reply":{"type":"boolean","example":false},"is_web":{"type":"integer","example":0},"folder":{"type":"string","example":"Admin Utilities","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CommandFolder":{"type":"object","properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Admin Utilities"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"DeletedCommand":{"type":"object","properties":{"_id":{"type":"string","example":"60c72b2f9b1d8a25c8d23456"},"bot_id":{"type":"integer","example":123456},"owner_id":{"type":"string","example":"60c72b2f9b1d8b3d88888888"},"command":{"$ref":"#/components/schemas/Command"},"deleted_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}}},"EnvironmentVariable":{"type":"object","properties":{"id":{"type":"integer","example":1},"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"API_URL"},"value":{"type":"string","example":"https://api.example.com"},"placeholder":{"type":"string","example":"Main backend server URL"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"StoreBot":{"type":"object","properties":{"_id":{"type":"string","example":"665a1b2c3d4e5f6789012345"},"bot_id":{"type":"integer","example":123456789012345},"name":{"type":"string","example":"Weather Bot"},"username":{"type":"string","example":"weather_updates_bot"},"description":{"type":"string","example":"Get live weather alerts in your Telegram groups."},"category":{"type":"string","example":"Utility"},"tags":{"type":"array","items":{"type":"string"},"example":["weather","alerts"]},"image":{"type":"string","example":"https://t.me/i/userpic/320/weather_updates_bot.jpg"},"developer":{"type":"string","example":"Community"},"rating":{"type":"number","example":4.5},"bot_url":{"type":"string","example":"https://t.me/weather_updates_bot"},"install_count":{"type":"integer","example":128},"last_installed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PublishedBotSummary":{"type":"object","description":"A bot published on a user profile — either a Bot Template or a Community Store Listing.","properties":{"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"Weather Bot"},"photo":{"type":"string","example":"https://t.me/i/userpic/320/my_weather_bot.jpg"},"bot_username":{"type":"string","example":"my_weather_bot"},"owner_username":{"type":"string","example":"johndoe","nullable":true},"listing_type":{"type":"string","enum":["bot_template","community_store"],"example":"bot_template","description":"bot_template = shareable blueprint. community_store = listed in the community store."},"listing_type_label":{"type":"string","example":"Bot Template"},"description":{"type":"string","example":"Short summary shown in listings."},"commands_count":{"type":"integer","example":4},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PublishedBotDetail":{"type":"object","description":"Full published bot profile including description, README, commands, and env placeholders.","properties":{"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"Weather Bot"},"photo":{"type":"string","example":"https://t.me/i/userpic/320/my_weather_bot.jpg"},"bot_username":{"type":"string","example":"my_weather_bot"},"owner_username":{"type":"string","example":"johndoe","nullable":true},"listing_type":{"type":"string","enum":["bot_template","community_store"],"example":"bot_template"},"listing_type_label":{"type":"string","example":"Bot Template"},"description":{"type":"string","example":"Short summary shown in listings."},"readme":{"type":"string","example":"# Weather Bot\\n\\nFull setup guide in markdown."},"commands_count":{"type":"integer","example":4},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"profile_path":{"type":"string","example":"/public/user/johndoe/bots/my_weather_bot","nullable":true},"readme_path":{"type":"string","example":"/public/user/johndoe/bots/my_weather_bot/readme","nullable":true},"envs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"API_KEY"},"placeholder":{"type":"string","example":"Required key"},"value":{"type":"string","nullable":true,"example":null}}}},"commands":{"type":"array","items":{"$ref":"#/components/schemas/Command"}}}},"BotTemplateDetail":{"type":"object","description":"A shareable bot blueprint (is_template = 1). Always has listing_type bot_template.","properties":{"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"My Template Bot"},"photo":{"type":"string","example":"https://ui-avatars.com/api/?name=M&background=random"},"bot_username":{"type":"string","example":"my_template_bot"},"owner_username":{"type":"string","example":"johndoe","nullable":true},"listing_type":{"type":"string","enum":["bot_template"],"example":"bot_template"},"listing_type_label":{"type":"string","example":"Bot Template"},"description":{"type":"string","example":"A template bot description"},"readme":{"type":"string","example":"# My Template Bot\\n\\nSetup guide in markdown."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"commands_count":{"type":"integer","example":1},"profile_path":{"type":"string","example":"/public/user/johndoe/bots/my_template_bot","nullable":true},"readme_path":{"type":"string","example":"/public/templates/123456/readme","nullable":true},"envs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"API_KEY"},"placeholder":{"type":"string","example":"Required key"},"value":{"type":"string","nullable":true,"example":null}}}},"commands":{"type":"array","items":{"$ref":"#/components/schemas/Command"}}}}}},"paths":{"/public/ads":{"get":{"tags":["Public Ads"],"summary":"Retrieve all active, non-expired advertisements","description":"Fetches active advertisements filtered by active status and non-expired time criteria. Returns an empty array if no advertisements are available.","responses":{"200":{"description":"Advertisements retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"ads":{"type":"array","items":{"$ref":"#/components/schemas/Ad"}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":15}}}}}}}}}}},"/status":{"get":{"tags":["Health"],"summary":"API health and status probe","description":"Retrieves current version, health status, and active environment.","responses":{"200":{"description":"Status payload retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","example":"v1"},"status":{"type":"string","example":"ok"},"env":{"type":"string","enum":["prod","dev"],"example":"prod"}}}}}}}}},"/public/user/{username}":{"get":{"tags":["Public Access"],"summary":"Get public profile","description":"Retrieves public information about a user. No authentication required.","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"},"description":"The user's public username."}],"responses":{"200":{"description":"Public profile data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"user":{"type":"object","properties":{"id":{"type":"string","example":"60c72b2f9b1d8a25c8d23456"},"profile":{"type":"object","properties":{"name":{"type":"string","example":"John Doe"},"username":{"type":"string","example":"johndoe"},"location":{"type":"string","example":"San Francisco, CA","nullable":true},"bio":{"type":"string","example":"Just another bot coder.","nullable":true},"avatar":{"type":"string","example":"https://example.com/avatar.jpg","nullable":true},"is_verified":{"type":"boolean","example":false}}},"stats":{"type":"object","properties":{"published_bots":{"type":"integer","example":5,"description":"Total published bots (templates + store listings)."},"bot_templates":{"type":"integer","example":3,"description":"Shareable bot blueprints (listing_type: bot_template)."},"community_store_listings":{"type":"integer","example":2,"description":"Bots listed in the community store (listing_type: community_store)."}}},"published_bots_path":{"type":"string","example":"/public/user/johndoe/bots"},"created_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":8}}}}}}}},"400":{"description":"Invalid username parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"reason":"invalid_input","message":"Username must be a string"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"reason":"user_not_found","message":"User not found"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"reason":"internal_error","message":"Get public profile handler error"}}}}}}},"/public/user/{username}/bots":{"get":{"tags":["Public Access"],"summary":"List a user's published bots","description":"Returns bot templates and community store listings owned by the user. Each item includes listing_type to distinguish them. No authentication required.","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","example":"johndoe"},"description":"The owner's username."},{"name":"page","in":"query","required":false,"schema":{"type":"string","example":"1"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string","example":"20"}},{"name":"listing_type","in":"query","required":false,"schema":{"type":"string","enum":["all","bot_template","community_store"],"example":"all"},"description":"Filter: bot_template (shareable blueprint) or community_store (store listing)."},{"name":"type","in":"query","required":false,"deprecated":true,"schema":{"type":"string","enum":["all","template","store"],"example":"all"},"description":"Deprecated alias for listing_type. Use listing_type instead."}],"responses":{"200":{"description":"Published bots retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"username":{"type":"string","example":"johndoe"},"published_bots":{"type":"array","items":{"$ref":"#/components/schemas/PublishedBotSummary"}},"pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20},"total":{"type":"integer","example":5},"pages":{"type":"integer","example":1}}},"meta":{"type":"object","properties":{"cached":{"type":"boolean","example":false},"processing_time_ms":{"type":"number","example":12}}}}}}}},"400":{"description":"Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"reason":"invalid_input","message":"Username cannot be empty"}}}},"404":{"description":"User not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"reason":"user_not_found","message":"User not found"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Failed to retrieve published bots."}}}}}}},"/public/user/{username}/bots/{botUsername}":{"get":{"tags":["Public Access"],"summary":"Get a published bot by Telegram username","description":"Returns full details for one published bot (bot template or community store listing), including description, README markdown, commands, and env placeholders. No authentication required.","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","example":"johndoe"}},{"name":"botUsername","in":"path","required":true,"schema":{"type":"string","example":"my_weather_bot"},"description":"Telegram bot username without @."}],"responses":{"200":{"description":"Published bot retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"published_bot":{"$ref":"#/components/schemas/PublishedBotDetail"},"meta":{"type":"object","properties":{"cached":{"type":"boolean","example":false},"processing_time_ms":{"type":"number","example":10}}}}}}}},"400":{"description":"Invalid username parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"reason":"invalid_input","message":"Username cannot be empty"}}}},"404":{"description":"User or bot not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"reason":"bot_not_found","message":"Bot not found"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Failed to retrieve published bot."}}}}}}},"/public/user/{username}/bots/{botUsername}/readme":{"get":{"tags":["Public Access"],"summary":"Get published bot README only","description":"Returns only the description and README markdown for a published bot. Use the bot detail endpoint for the full profile including commands. No authentication required.","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string","example":"johndoe"}},{"name":"botUsername","in":"path","required":true,"schema":{"type":"string","example":"my_weather_bot"}}],"responses":{"200":{"description":"Bot README retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"bot_id":{"type":"integer","example":123456},"bot_username":{"type":"string","example":"my_weather_bot"},"owner_username":{"type":"string","example":"johndoe"},"listing_type":{"type":"string","enum":["bot_template","community_store"],"example":"bot_template"},"listing_type_label":{"type":"string","example":"Bot Template"},"description":{"type":"string","example":"Short bot description."},"readme":{"type":"string","example":"# Weather Bot\\n\\nSetup instructions..."},"meta":{"type":"object","properties":{"cached":{"type":"boolean","example":true},"processing_time_ms":{"type":"number","example":10}}}}}}}},"400":{"description":"Invalid username parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"reason":"invalid_input","message":"Username cannot be empty"}}}},"404":{"description":"User or bot not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"reason":"bot_not_found","message":"Bot not found"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Failed to retrieve bot readme."}}}}}}},"/bot":{"get":{"tags":["Bot Management"],"summary":"List user bots","description":"Retrieves all registered bots belonging to the user. Accessible by developer API keys.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"List of bots and statistics","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"stats":{"type":"object","properties":{"total":{"type":"integer","example":1},"public_store":{"type":"integer","example":0},"transferred":{"type":"integer","example":0},"cloned":{"type":"integer","example":0},"templates":{"type":"integer","example":0}}},"bots":{"type":"array","items":{"$ref":"#/components/schemas/BotListItem"}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}},"post":{"tags":["Bot Management"],"summary":"Register a new bot","description":"Registers a new bot under the caller's account. Accessible via web session cookie OR developer API keys (sk_*). Subject to plan-based creation rate limits (e.g. 1 request per 5 minutes on FREE/FREEMIUM plans).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bot_token"],"properties":{"bot_token":{"type":"string","example":"123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ"},"bot_name":{"type":"string","example":"MyAwesomeBot","description":"Optional. Defaults to the Telegram bot first name when omitted."},"run_now":{"type":"boolean","example":false}}}}}},"responses":{"201":{"description":"Bot registered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Telegram bot registered successfully."},"bot":{"$ref":"#/components/schemas/BotListItem"},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":120}}}}}}}},"400":{"description":"Invalid input or bot token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Invalid Telegram Bot Token."}}}},"403":{"description":"Forbidden (read-only key used)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Read-only key used"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Failed to register bot due to an internal error."}}}},"502":{"description":"Bad gateway (failed to register webhook with Telegram)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Failed to set Telegram webhook."}}}}}},"delete":{"tags":["Bot Management"],"summary":"Delete registered bot(s)","description":"Performs a soft deletion on one or more bots, moving them to a backup for 10 days during which they can be recovered. **Requires write/secret key or session cookie**.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"integer"},"example":[123456],"description":"A single bot ID or an array of bot IDs to delete"}}}}}},"responses":{"200":{"description":"Bots deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bots deletion completed."},"deleted_count":{"type":"integer","example":1},"requested_count":{"type":"integer","example":1},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"403":{"description":"Read-only key used","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/bot/deleted":{"get":{"tags":["Bot Management"],"summary":"List soft-deleted bots","description":"Retrieves all soft-deleted bots belonging to the user that are currently in the 10-day backup. Accessible by developer API keys.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"responses":{"200":{"description":"List of soft-deleted bots","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"bots":{"type":"array","items":{"type":"object","properties":{"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"My Telegram Bot"},"photo":{"type":"string","example":"https://t.me/i/userpic/320/my_telegram_bot.jpg"},"bot_username":{"type":"string","example":"my_telegram_bot"},"status":{"type":"integer","example":0},"deleted_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}}},"/bot/deleted/{botid}/recover":{"post":{"tags":["Bot Management"],"summary":"Recover soft-deleted bot","description":"Restores a soft-deleted bot from backup back to the active bots collection. **The bot will be recovered with status 0 (disabled) for safety**.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID to recover"}],"responses":{"200":{"description":"Bot successfully recovered","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bot successfully recovered."},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"404":{"description":"Deleted bot not found in backup"}}}},"/bot/deleted/{botid}/permanent":{"delete":{"tags":["Bot Management"],"summary":"Permanently delete soft-deleted bot","description":"Permanently purges a soft-deleted bot and all of its associated logs, users, and session records from backup.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID to permanently delete"}],"responses":{"200":{"description":"Bot permanently deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bot permanently deleted."},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"404":{"description":"Deleted bot not found in backup"}}}},"/bot/pin":{"patch":{"tags":["Bot Management"],"summary":"Pin or unpin bot(s)","description":"Updates the pin status for one or more bots. **Requires write/secret key or session cookie**.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids","pin"],"properties":{"ids":{"type":"array","items":{"type":"integer"},"example":[123456],"description":"A single bot ID or an array of bot IDs to pin/unpin"},"pin":{"type":"boolean","example":true,"description":"True to pin, false to unpin"}}}}}},"responses":{"200":{"description":"Pin state updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bots pinned successfully."},"updated":{"type":"array","items":{"$ref":"#/components/schemas/BotListItem"}},"bots":{"type":"array","items":{"$ref":"#/components/schemas/BotListItem"}},"stats":{"type":"object","properties":{"total":{"type":"integer","example":1},"public_store":{"type":"integer","example":0},"transferred":{"type":"integer","example":0},"cloned":{"type":"integer","example":0},"templates":{"type":"integer","example":0}}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"403":{"description":"Read-only key used","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/bot/{botid}":{"get":{"tags":["Bot Management"],"summary":"Get single bot details","description":"Retrieves profile of a specific bot by ID.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"Bot details retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"bot":{"$ref":"#/components/schemas/Bot"},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"404":{"description":"Bot not found"}}},"patch":{"tags":["Bot Management"],"summary":"Update bot configuration","description":"Updates specific attributes of the registered bot. **Requires write/secret key or session cookie**.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"NewBotName"},"bot_token":{"type":"string","example":"987654321:XYZabcDef..."},"pin":{"type":"boolean","example":true},"status":{"type":"integer","example":1}}}}}},"responses":{"200":{"description":"Bot updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bot details updated successfully."},"updated":{"$ref":"#/components/schemas/BotListItem"},"bots":{"type":"array","items":{"$ref":"#/components/schemas/BotListItem"}},"stats":{"type":"object","properties":{"total":{"type":"integer","example":1},"public_store":{"type":"integer","example":0},"transferred":{"type":"integer","example":0},"cloned":{"type":"integer","example":0},"templates":{"type":"integer","example":0}}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":12}}}}}}}},"403":{"description":"Read-only key used"},"404":{"description":"Bot not found"}}}},"/bot/{botid}/export":{"get":{"tags":["Bot Management"],"summary":"Generate temporary bot export download link","description":"Generates a temporary JWT token and download URL for exporting the bot.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"Temporary download URL successfully generated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"download_url":{"type":"string","example":"http://localhost:3000/api/v1/bot/download?token=jwt_token"},"expires_in_seconds":{"type":"integer","example":300},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"404":{"description":"Bot not found"}}}},"/bot/download":{"get":{"tags":["Bot Management"],"summary":"Download bot configuration package","description":"Downloads the bot configuration as a ZIP package containing bot.yaml, .env, and commands directory. Requires a valid temporary JWT token query parameter.","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"},"description":"The temporary download JWT token"}],"responses":{"200":{"description":"Returns bot configuration ZIP package","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid token"},"404":{"description":"Bot not found"},"410":{"description":"Expired download token"}}}},"/bot/import":{"post":{"tags":["Bot Management"],"summary":"Import bot from ZIP package","description":"Imports a bot from a ZIP upload. Requires a multipart form-data payload containing the zip file. Accessible via web session cookie OR developer API keys (sk_*). Subject to plan-based creation rate limits (e.g. 1 request per 5 minutes on FREE/FREEMIUM plans).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The bot configuration ZIP file"}}}}}},"responses":{"201":{"description":"Bot imported successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bot imported successfully."},"bot":{"type":"object","properties":{"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"My Imported Bot"},"photo":{"type":"string","example":"https://ui-avatars.com/api/?name=M&background=random"},"bot_username":{"type":"string","example":"my_imported_bot"},"status":{"type":"integer","example":0}}}}}}}},"400":{"description":"Invalid zip package, signature, or structure"}}}},"/bot/{botid}/clone":{"post":{"tags":["Bot Management"],"summary":"Clone an existing bot","description":"Duplicates an owned bot or a public template bot under the user's account. Accessible via web session cookie OR developer API keys (sk_*). Subject to plan-based creation rate limits (e.g. 1 request per 5 minutes on FREE/FREEMIUM plans). Subject to bot cloning rate limits (1/sec, 5/min, 20/hr).","security":[{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"201":{"description":"Bot cloned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bot cloned successfully."},"bot":{"type":"object","properties":{"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"Cloned Bot"},"photo":{"type":"string","example":"https://ui-avatars.com/api/?name=C&background=random"},"bot_username":{"type":"string","example":"cloned_bot"},"status":{"type":"integer","example":0},"is_cloned":{"type":"integer","example":1}}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"403":{"description":"Unauthorized clone attempt of a private bot"},"404":{"description":"Source bot not found"},"429":{"description":"Bot cloning rate limit exceeded."}}}},"/bot/{botid}/clone-child":{"post":{"tags":["Bot Management"],"summary":"Clone a bot as a child bot","description":"Clones an owned parent bot or a public template bot as a child bot under the user's account. Child bots dynamically inherit environment variables and commands/folders from the parent bot without copying or duplicating configuration arrays in the database. Accessible via web session cookie OR developer API keys (sk_*). Subject to plan-based creation rate limits. Subject to bot cloning rate limits (1/sec, 5/min, 20/hr).","security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric parent bot ID"}],"responses":{"201":{"description":"Bot cloned as a child successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bot cloned as a child successfully."},"bot":{"type":"object","properties":{"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"Child Bot"},"photo":{"type":"string","example":"https://ui-avatars.com/api/?name=C&background=random"},"bot_username":{"type":"string","example":"child_bot"},"status":{"type":"integer","example":0},"is_child":{"type":"integer","example":1},"parent_id":{"type":"integer","example":77778888}}}}}}}},"403":{"description":"Forbidden - Unauthorized clone attempt (not owner or template) or plan creation limits exceeded"},"404":{"description":"Not Found - Parent bot to clone not found"},"429":{"description":"Bot cloning rate limit exceeded."}}}},"/bot/{botid}/children":{"get":{"tags":["Bot Management"],"summary":"List children of a parent bot","description":"Retrieves all child bots registered under the specified parent bot. Accessible via web session cookie OR developer API keys (sk_* / pub_*).","security":[{"bearerAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric parent bot ID"}],"responses":{"200":{"description":"Children bots listed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"children":{"type":"array","items":{"type":"object","properties":{"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"Child Bot"},"photo":{"type":"string","example":"https://ui-avatars.com/api/?name=C&background=random"},"bot_username":{"type":"string","example":"child_bot"},"status":{"type":"integer","example":0},"pin":{"type":"boolean","example":false},"created_at":{"type":"string","format":"date-time","example":"2026-06-23T08:15:30.000Z"},"updated_at":{"type":"string","format":"date-time","example":"2026-06-23T08:15:30.000Z"},"blocked":{"type":"integer","example":0},"uptime":{"type":"string","example":"0d 0h 0m"},"is_child":{"type":"integer","example":1},"parent_id":{"type":"integer","example":77778888}}}},"total":{"type":"integer","example":1}}}}}},"403":{"description":"Forbidden - Unauthorized attempt to view child bots of this parent (not the owner)"},"404":{"description":"Not Found - Parent bot not found"}}}},"/bot/{botid}/transfer":{"post":{"tags":["Bot Management"],"summary":"Transfer bot to another user","description":"Transfers the bot to a target user (identified by their user ID or email address). Note that the transfer operation actually clones the same bot into the target user's account: the original bot is preserved on the sender's account, and a new clone of the bot is provisioned on the receiver's account with blank credentials (status 0, null token) and reset environment variables. All other configurations and command structures are duplicated.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target"],"properties":{"target":{"type":"string","example":"receiver@example.com","description":"The target user's email or user ID"}}}}}},"responses":{"201":{"description":"Bot transferred successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bot transferred successfully."},"bot":{"type":"object","properties":{"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"Transferred Bot"},"photo":{"type":"string","example":"https://ui-avatars.com/api/?name=T&background=random"},"bot_username":{"type":"string","example":"transferred_bot"},"status":{"type":"integer","example":0},"is_transferred":{"type":"integer","example":1}}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"400":{"description":"Bad Request - Invalid path parameters or request body format.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Invalid request body."},"errors":{"type":"object"}}}}}},"401":{"description":"Unauthorized - Missing or invalid credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"reason":{"type":"string","example":"no_credentials"}}}}}},"403":{"description":"Forbidden - User does not have permission to transfer this bot (not the owner).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Bot not found or you do not have permission to transfer this bot."}}}}}},"404":{"description":"Not Found - The specified bot or target receiver user was not found.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Target user not found."}}}}}},"500":{"description":"Internal Server Error - Encountered an unexpected error processing the transfer.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string","example":"Failed to transfer bot due to an internal error."}}}}}}}}},"/bot/{botid}/reset":{"post":{"tags":["Bot Management"],"summary":"Reset bot logs and sessions","description":"Deletes all records from bot logs, bot sessions, and flags all bot users as just created.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"Bot reset completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bot reset successfully."},"logs_deleted":{"type":"integer","example":5},"sessions_deleted":{"type":"integer","example":2},"users_updated":{"type":"integer","example":12},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"404":{"description":"Bot not found"}}}},"/bot/{botid}/template":{"patch":{"tags":["Bot Management"],"summary":"Toggle bot template status","description":"Toggles the is_template flag for the specified bot.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["is_template"],"properties":{"is_template":{"type":"boolean","example":true}}}}}},"responses":{"200":{"description":"Template status updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bot template status updated to true."},"bot_id":{"type":"integer","example":123456},"is_template":{"type":"integer","example":1},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"404":{"description":"Bot not found"}}}},"/bot/{botid}/readme":{"get":{"tags":["Bot Management"],"summary":"Get bot description and README","description":"Retrieves the description and README markdown privately for the bot owner.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"README details retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"bot_id":{"type":"integer","example":123456},"description":{"type":"string","example":"A Telegram bot"},"readme":{"type":"string","example":"# My Bot README"}}}}}},"404":{"description":"Bot not found"}}},"put":{"tags":["Bot Management"],"summary":"Update bot description and README","description":"Saves or updates description and README markdown. Only allowed if the bot has been marked as a template.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","maxLength":500,"example":"A Telegram bot description"},"readme":{"type":"string","maxLength":50000,"example":"# Bot Description"}}}}}},"responses":{"200":{"description":"Metadata updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bot description and README saved successfully."}}}}}},"400":{"description":"Bot is not published as a template"},"404":{"description":"Bot not found"}}}},"/bot/{botid}/storage/stats":{"get":{"tags":["Bot Management"],"summary":"Get bot storage statistics","description":"Retrieves sync and async storage size and key metrics for a specific bot and its users. Requires ownership check.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Bypasses cache if set to true or 1."}],"responses":{"200":{"description":"Bot storage stats retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"bot_id":{"type":"integer","example":12345},"owner_id":{"type":"string","example":"507f1f77bcf86cd799439011"},"sync":{"type":"object","properties":{"bot_props_count":{"type":"integer","example":5},"bot_props_size_bytes":{"type":"integer","example":512},"bot_keys":{"type":"array","items":{"type":"string"},"example":["theme","lang","welcome"]},"user_docs_count":{"type":"integer","example":30},"user_props_count":{"type":"integer","example":90},"user_props_size_bytes":{"type":"integer","example":8192},"total_size_bytes":{"type":"integer","example":8704}}},"async":{"type":"object","properties":{"bot_props_count":{"type":"integer","example":8},"bot_props_size_bytes":{"type":"integer","example":4096},"bot_keys":{"type":"array","items":{"type":"string"},"example":["score","level","config"]},"user_props_count":{"type":"integer","example":150},"user_props_size_bytes":{"type":"integer","example":12288},"total_size_bytes":{"type":"integer","example":16384}}},"total_size_bytes":{"type":"integer","example":25088},"total_size_mb":{"type":"string","example":"0.02"},"cached_at":{"type":"string","format":"date-time","example":"2026-06-29T12:00:00.000Z"},"cached":{"type":"boolean","example":true}}}}}}}},"404":{"description":"Bot not found or access denied"}}}},"/bot/{botid}/storage/data":{"get":{"tags":["Bot Management"],"summary":"Get bot storage data keys (detail)","description":"Retrieves bot keys detail without showing values. Requires ownership check.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Bypasses cache if set to true or 1."}],"responses":{"200":{"description":"Bot storage keys detail retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"bot_id":{"type":"integer","example":12345},"owner_id":{"type":"string","example":"507f1f77bcf86cd799439011"},"sync":{"type":"object","properties":{"bot_props_count":{"type":"integer","example":5},"bot_props_size_bytes":{"type":"integer","example":512},"bot_keys":{"type":"array","items":{"type":"string"},"example":["theme","lang","welcome"]},"user_docs_count":{"type":"integer","example":30},"user_props_count":{"type":"integer","example":90},"user_props_size_bytes":{"type":"integer","example":8192},"total_size_bytes":{"type":"integer","example":8704}}},"async":{"type":"object","properties":{"bot_props_count":{"type":"integer","example":8},"bot_props_size_bytes":{"type":"integer","example":4096},"bot_keys":{"type":"array","items":{"type":"string"},"example":["score","level","config"]},"user_props_count":{"type":"integer","example":150},"user_props_size_bytes":{"type":"integer","example":12288},"total_size_bytes":{"type":"integer","example":16384}}},"total_size_bytes":{"type":"integer","example":25088},"total_size_mb":{"type":"string","example":"0.02"},"cached_at":{"type":"string","format":"date-time","example":"2026-06-29T12:00:00.000Z"},"cached":{"type":"boolean","example":true}}}}}}}},"404":{"description":"Bot not found or access denied"}}},"delete":{"tags":["Bot Management"],"summary":"Clear bot storage data (sync + async)","description":"Permanently deletes all sync and async props for the bot and user props associated with it. Requires ownership check.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"Bot data cleared successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bot 12345 data cleared successfully"},"data":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"bot_id":{"type":"integer","example":12345},"async":{"type":"object","properties":{"bot_props_deleted":{"type":"integer","example":8},"user_props_deleted":{"type":"integer","example":150},"size_freed_bytes":{"type":"integer","example":16384}}},"sync":{"type":"object","properties":{"bot_props_deleted":{"type":"integer","example":1},"user_docs_deleted":{"type":"integer","example":30},"size_freed_bytes":{"type":"integer","example":512}}},"total_deleted":{"type":"integer","example":189},"size_freed_bytes":{"type":"integer","example":16896}}}}}}}},"404":{"description":"Bot not found or access denied"}}}},"/bot/{botid}/storage/migrate":{"post":{"tags":["Bot Management"],"summary":"Migrate bot sync storage to async","description":"Migrates sync Bot.setProp data to async db.xx storage on the executor. Owner is resolved from the bot record.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["bot","user","both"],"default":"both"},"dryRun":{"type":"boolean","default":false},"overwrite":{"type":"boolean","default":false},"deleteSource":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Migration completed or dry-run preview returned"},"404":{"description":"Bot not found or access denied"}}}},"/bot/{botid}/broadcast":{"post":{"tags":["Bot Management"],"summary":"Start a bot broadcast job","description":"Initiates a broadcast sending a command trigger or message template to all bot subscribers matching the given filters. Owner checks are enforced.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"method":{"type":"string","example":"sendMessage"},"body":{"type":"object","properties":{"text":{"type":"string","example":"Hello Subscribers!"}}},"filters":{"type":"object","properties":{"chatType":{"oneOf":[{"type":"string","enum":["all","private","group","channel"]},{"type":"array","items":{"type":"string","enum":["all","private","group","channel"]}}],"description":"Target specific chat types. Can be a single chat type or an array of multiple chat types to target simultaneously.","example":["private","group"]},"premiumOnly":{"type":"boolean","example":false}}}}}}}},"responses":{"200":{"description":"Broadcast task queued successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"broadcastId":{"type":"string","example":"d3b07384-d113-4ec2-a5d9-482d2086e1ec"},"totalTargetChats":{"type":"integer","example":120},"totalBatches":{"type":"integer","example":1}}}}}},"404":{"description":"Bot not found or access denied"}}}},"/bot/{botid}/broadcast/stats/{broadcastId}":{"get":{"tags":["Bot Management"],"summary":"Get bot broadcast stats","description":"Retrieves real-time progress metrics and status of a broadcast. Requires bot ownership check.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"}},{"name":"broadcastId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Broadcast stats retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"broadcast_id":{"type":"string","example":"d3b07384-d113-4ec2-a5d9-482d2086e1ec"},"bot_ids":{"type":"array","items":{"type":"integer"},"example":[12345]},"status":{"type":"string","example":"processing"},"total_chats":{"type":"integer","example":120},"processed_count":{"type":"integer","example":50},"success_count":{"type":"integer","example":48},"fail_count":{"type":"integer","example":2},"pruned_count":{"type":"integer","example":0},"total_batches":{"type":"integer","example":1},"completed_batches":{"type":"integer","example":0},"created_at":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Bot or broadcast job not found, or access denied"}}}},"/bot/{botid}/broadcast/stop/{broadcastId}":{"post":{"tags":["Bot Management"],"summary":"Stop an active bot broadcast","description":"Stops a processing broadcast job immediately. Requires bot ownership check.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"}},{"name":"broadcastId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Broadcast job stopped","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Broadcast stopped successfully"}}}}}},"404":{"description":"Bot or broadcast job not found, or access denied"}}}},"/bot/{botid}/broadcast/modify/{broadcastId}":{"put":{"tags":["Bot Management"],"summary":"Modify active bot broadcast parameters","description":"Allows modifying the message body mid-run for any pending batches. Requires bot ownership check.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"}},{"name":"broadcastId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"object","properties":{"text":{"type":"string","example":"Updated subscriber text."}}}}}}}},"responses":{"200":{"description":"Broadcast parameters updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Broadcast parameters updated for pending batches"}}}}}},"404":{"description":"Bot or broadcast job not found, or access denied"}}}},"/bot/{botid}/broadcast/delete/{broadcastId}":{"delete":{"tags":["Bot Management"],"summary":"Delete bot broadcast history log","description":"Deletes the completed or stopped broadcast tracking record and cleans Redis keys. Requires bot ownership check.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"}},{"name":"broadcastId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Broadcast job fully deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Broadcast job fully deleted from database"}}}}}},"404":{"description":"Bot or broadcast job not found, or access denied"}}}},"/bot/{botid}/broadcast/list":{"get":{"tags":["Bot Management"],"summary":"List broadcasts for a bot","description":"Retrieves the full list of broadcasts queued or run for a specific bot. Requires bot ownership check.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Comma-separated list of statuses to filter by (e.g. pending,processing,completed,failed,stopped)","schema":{"type":"string"}},{"name":"all","in":"query","required":false,"description":"Set to true to retrieve broadcasts across all statuses","schema":{"type":"string"}}],"responses":{"200":{"description":"List of broadcasts retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"ok":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string","example":"60c72b2f9b1d8e2b8c8d8f8a"},"broadcast_id":{"type":"string","example":"d3b07384-d113-4ec2-a5d9-482d2086e1ec"},"bot_ids":{"type":"array","items":{"type":"number"},"example":[123456]},"runner_user_id":{"type":"string","example":"60c72b2f9b1d8e2b8c8d8f80"},"status":{"type":"string","example":"processing"},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"404":{"description":"Bot not found or access denied"}}}},"/public/templates":{"get":{"tags":["Public Access"],"summary":"List bot templates (explore)","description":"Browse shareable bot blueprints (listing_type: bot_template). For community store listings use GET /public/store/bots. No authentication required.","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"string","example":"1"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string","example":"10"}},{"name":"search","in":"query","required":false,"schema":{"type":"string","example":"search_term"}}],"responses":{"200":{"description":"Templates list retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"templates":{"type":"array","items":{"type":"object","properties":{"bot_id":{"type":"integer","example":123456},"name":{"type":"string","example":"My Template Bot"},"photo":{"type":"string","example":"https://ui-avatars.com/api/?name=M&background=random"},"bot_username":{"type":"string","example":"my_template_bot"},"owner_username":{"type":"string","example":"johndoe","nullable":true},"listing_type":{"type":"string","enum":["bot_template"],"example":"bot_template"},"listing_type_label":{"type":"string","example":"Bot Template"},"profile_path":{"type":"string","example":"/public/user/johndoe/bots/my_template_bot","nullable":true},"description":{"type":"string","example":"A template bot description"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"commands_count":{"type":"integer","example":1},"envs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"API_KEY"},"placeholder":{"type":"string","example":"Required key"},"value":{"type":"string","nullable":true,"example":null}}}},"commands":{"type":"array","items":{"$ref":"#/components/schemas/Command"}}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":10},"total":{"type":"integer","example":1}}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Failed to retrieve templates due to an internal error."}}}}}}},"/public/templates/{botid}":{"get":{"tags":["Public Access"],"summary":"Get a bot template by ID","description":"Returns one shareable bot blueprint (listing_type: bot_template) including description, README markdown, commands, and env placeholders. No authentication required.","parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string","example":"123456789012345"}}],"responses":{"200":{"description":"Template retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"template":{"$ref":"#/components/schemas/BotTemplateDetail"},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"404":{"description":"Template not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Public template not found."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Failed to retrieve template."}}}}}}},"/public/templates/{botid}/readme":{"get":{"tags":["Public Access"],"summary":"Get public template README details","description":"Retrieves the public description and README markdown for a template bot. Uses caching for performance.","parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"Template README retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"bot_id":{"type":"integer","example":123456},"description":{"type":"string","example":"A template bot"},"readme":{"type":"string","example":"# Template Bot README"},"meta":{"type":"object","properties":{"cached":{"type":"boolean","example":true},"processing_time_ms":{"type":"number","example":10}}}}}}}},"400":{"description":"Invalid bot ID parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Invalid path parameters."}}}},"404":{"description":"Template not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Public template not found."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Failed to retrieve readme due to an internal error."}}}}}}},"/public/store/bots":{"get":{"tags":["Public Access"],"summary":"Browse community store (public)","description":"Public discovery endpoint for the community bot store. Same data as the authenticated store list but requires no login. No authentication required.","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","example":"Utility"}},{"name":"search","in":"query","required":false,"schema":{"type":"string","example":"weather"}},{"name":"page","in":"query","required":false,"schema":{"type":"string","example":"1"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string","example":"20"}}],"responses":{"200":{"description":"Store bots retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"bots":{"type":"array","items":{"$ref":"#/components/schemas/StoreBot"}},"pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20},"total":{"type":"integer","example":42},"pages":{"type":"integer","example":3}}},"meta":{"type":"object","properties":{"cached":{"type":"boolean","example":true},"processing_time_ms":{"type":"number","example":12}}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Invalid query parameters."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Failed to retrieve store bots."}}}}}}},"/public/store/bots/{botMetaId}":{"get":{"tags":["Public Access"],"summary":"Get a community store listing (public)","description":"Returns one store listing with owner username and a link to the owner profile path. No authentication required.","parameters":[{"name":"botMetaId","in":"path","required":true,"schema":{"type":"string","example":"665a1b2c3d4e5f6789012345"}}],"responses":{"200":{"description":"Store listing retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"bot":{"allOf":[{"$ref":"#/components/schemas/StoreBot"},{"type":"object","properties":{"owner_username":{"type":"string","example":"johndoe","nullable":true},"profile_path":{"type":"string","example":"/public/user/johndoe/bots/my_weather_bot","nullable":true}}}]},"meta":{"type":"object","properties":{"cached":{"type":"boolean","example":false},"processing_time_ms":{"type":"number","example":10}}}}}}}},"400":{"description":"Invalid store listing ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Invalid store listing ID."}}}},"404":{"description":"Store listing not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"reason":"store_bot_not_found","message":"Store bot listing not found."}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"message":"Failed to retrieve store bot."}}}}}}},"/store/bots":{"get":{"tags":["Community Bot Store"],"summary":"List community store bots","description":"Returns all bots published in the community store, sorted by popularity (install count). Accessible via web session cookie or developer API keys.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","example":"Utility"},"description":"Filter by store category."},{"name":"search","in":"query","required":false,"schema":{"type":"string","example":"weather"},"description":"Search name, description, username, or tags (2–64 characters)."},{"name":"page","in":"query","required":false,"schema":{"type":"string","example":"1"},"description":"Page number (default 1)."},{"name":"limit","in":"query","required":false,"schema":{"type":"string","example":"20"},"description":"Results per page (default 20, max 50)."}],"responses":{"200":{"description":"Store bots retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"bots":{"type":"array","items":{"$ref":"#/components/schemas/StoreBot"}},"pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20},"total":{"type":"integer","example":42},"pages":{"type":"integer","example":3}}},"meta":{"type":"object","properties":{"cached":{"type":"boolean","example":true},"processing_time_ms":{"type":"number","example":12}}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Store browse rate limit exceeded"}}}},"/store/install/{botMetaId}":{"post":{"tags":["Community Bot Store"],"summary":"Install a community store bot","description":"Adds a community store bot to the authenticated user's account. Environment values are cleared and must be configured after install. Subject to store burst, daily, listing cooldown, and plan-based creation limits. Subject to store install rate limits (1/sec, 5/min, 20/hr).","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botMetaId","in":"path","required":true,"schema":{"type":"string","example":"665a1b2c3d4e5f6789012345"},"description":"The store listing ID returned from the list endpoint (`_id` field)."}],"responses":{"201":{"description":"Bot installed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Bot installed successfully."},"installedBot":{"type":"object","properties":{"bot_id":{"type":"integer","example":123456789012345},"bot_name":{"type":"string","example":"Weather Bot"},"commands_count":{"type":"integer","example":4},"envs_count":{"type":"integer","example":2}}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":18}}}}}}}},"400":{"description":"Invalid store listing ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Store bot not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Store install rate limit exceeded."}}}},"/bot/{botid}/commands":{"get":{"tags":["Commands Management"],"summary":"List bot commands","description":"Retrieves all commands registered for the specified bot.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"List of commands and folders","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"commands":{"type":"array","items":{"$ref":"#/components/schemas/Command"}},"folders":{"type":"array","items":{"$ref":"#/components/schemas/CommandFolder"}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}},"post":{"tags":["Commands Management"],"summary":"Create a new bot command","description":"Registers a new command configuration for the bot. Subject to creation rate limits (10/sec, 30/min, 200/hr) and bot capacity cap of 1000 commands / 10MB total command payload.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"/start"},"code":{"type":"string","example":"ctx.reply(\"Hello!\");"},"answer":{"type":"string","example":"Welcome"},"parse_mode":{"type":"string","example":"Markdown"},"keyboard":{"type":"string","example":"main_menu"},"aliases":{"type":"array","items":{"type":"string"},"example":["begin"]},"allow_only_group":{"type":"boolean","example":false},"need_reply":{"type":"boolean","example":false},"is_web":{"type":"integer","minimum":0,"maximum":1,"example":0},"folder":{"type":"string","example":"Admin Utilities","nullable":true,"description":"Optional folder name to assign this command to. Folder must exist."}}}}}},"responses":{"201":{"description":"Command created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Command created successfully."},"command":{"$ref":"#/components/schemas/Command"},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":15}}}}}}}},"400":{"description":"Capacity cap reached (max 1000 commands or 10MB total payload) or invalid payload."},"429":{"description":"Creation rate limit exceeded."}}},"delete":{"tags":["Commands Management"],"summary":"Delete multiple commands","description":"Deletes one or more commands from the bot in a single batch operation.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"integer"},"example":[1,2,3],"description":"Array of command database IDs to delete"}}}}}},"responses":{"200":{"description":"Commands deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"3 commands deleted successfully."},"deleted_count":{"type":"integer","example":3},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}}},"/bot/{botid}/commands/deleted":{"get":{"tags":["Commands Management"],"summary":"List deleted bot commands","description":"Retrieves all soft-deleted commands for the specified bot that are currently stored in the recovery collection (expires after 7 days).","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"List of soft-deleted commands","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"deleted_commands":{"type":"array","items":{"$ref":"#/components/schemas/DeletedCommand"}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}}},"/bot/{botid}/commands/deleted/{deletedid}/recover":{"post":{"tags":["Commands Management"],"summary":"Recover a deleted bot command","description":"Restores a soft-deleted bot command by its deletion record ID back into the bot's active commands array.","security":[{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"},{"name":"deletedid","in":"path","required":true,"schema":{"type":"string"},"description":"The unique ObjectId of the soft-deleted command record"}],"responses":{"200":{"description":"Command successfully recovered","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Command recovered successfully."},"command":{"$ref":"#/components/schemas/Command"},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":15}}}}}}}}},"/bot/{botid}/commands/deleted/{deletedid}":{"delete":{"tags":["Commands Management"],"summary":"Permanently delete a soft-deleted command","description":"Permanently deletes a soft-deleted command from the recovery backup collection. This action cannot be undone.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"},{"name":"deletedid","in":"path","required":true,"schema":{"type":"string"},"description":"The unique ObjectId of the soft-deleted command record"}],"responses":{"200":{"description":"Command permanently deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Command permanently deleted."},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}}},"/bot/{botid}/commands/{commandid}":{"get":{"tags":["Commands Management"],"summary":"Get bot command details","description":"Retrieves configuration details of a specific bot command.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"},{"name":"commandid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric command ID"}],"responses":{"200":{"description":"Command details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"command":{"$ref":"#/components/schemas/Command"},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}},"patch":{"tags":["Commands Management"],"summary":"Update bot command","description":"Updates configurable fields of a bot command.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"},{"name":"commandid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric command ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"/updated_start"},"code":{"type":"string","example":"ctx.reply(\"Updated\");"},"answer":{"type":"string","example":"Updated Welcome"},"parse_mode":{"type":"string","example":"Markdown"},"keyboard":{"type":"string","example":"updated_menu"},"aliases":{"type":"array","items":{"type":"string"},"example":["begin"]},"allow_only_group":{"type":"boolean","example":false},"need_reply":{"type":"boolean","example":false},"is_web":{"type":"integer","minimum":0,"maximum":1,"example":0},"folder":{"type":"string","example":"Admin Utilities","nullable":true,"description":"Optional folder name to assign this command to. Pass null to unassign from folder."}}}}}},"responses":{"200":{"description":"Command updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Command updated successfully."},"command":{"$ref":"#/components/schemas/Command"},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}},"delete":{"tags":["Commands Management"],"summary":"Delete single command","description":"Removes a specific command from the bot.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"},{"name":"commandid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric command ID"}],"responses":{"200":{"description":"Command deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Command deleted successfully."},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}}},"/bot/{botid}/commands/folders":{"get":{"tags":["Commands Management"],"summary":"List command folders","description":"Retrieves all folders created for organizing commands of the specified bot.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"List of command folders","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"folders":{"type":"array","items":{"$ref":"#/components/schemas/CommandFolder"}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}},"404":{"description":"Bot not found"}}},"post":{"tags":["Commands Management"],"summary":"Create a command folder","description":"Creates a new folder to categorize bot commands. Folder names must be unique (case-insensitive) per bot.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":50,"example":"Admin Utilities"}}}}}},"responses":{"201":{"description":"Folder created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Folder created successfully."},"folder":{"$ref":"#/components/schemas/CommandFolder"},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":15}}}}}}}},"400":{"description":"Invalid input or folder already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Bot not found"}}}},"/bot/{botid}/commands/folders/{folderid}":{"patch":{"tags":["Commands Management"],"summary":"Rename command folder","description":"Renames an existing command folder and automatically updates the folder property on all commands belonging to it.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"},{"name":"folderid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric folder ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":50,"example":"Moderation tools"}}}}}},"responses":{"200":{"description":"Folder renamed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Folder updated successfully."},"folder":{"type":"object","properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Moderation tools"},"updated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":15}}}}}}}},"400":{"description":"Invalid input or folder name collision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Bot or folder not found"}}},"delete":{"tags":["Commands Management"],"summary":"Delete command folder","description":"Deletes the specified command folder. Commands that belonged to this folder are unassigned (set to null) rather than deleted.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"},{"name":"folderid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric folder ID"}],"responses":{"200":{"description":"Folder deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Folder 'Admin Utilities' deleted. Commands have been unassigned."},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":15}}}}}}}},"404":{"description":"Bot or folder not found"}}}},"/bot/{botid}/envs":{"get":{"tags":["Environment Variables"],"summary":"List bot environment variables","description":"Retrieves all environment variables configured for the bot.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"List of environment variables","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"envs":{"type":"array","items":{"$ref":"#/components/schemas/EnvironmentVariable"}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}},"post":{"tags":["Environment Variables"],"summary":"Create environment variable","description":"Registers a new environment variable key-value pair for the bot.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"API_URL"},"value":{"type":"string","example":"https://api.example.com"},"placeholder":{"type":"string","example":"Backend integration URL"}}}}}},"responses":{"201":{"description":"Environment variable created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Env variable created successfully."},"env":{"$ref":"#/components/schemas/EnvironmentVariable"},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":15}}}}}}}}}}},"/bot/{botid}/envs/{envid}":{"get":{"tags":["Environment Variables"],"summary":"Get environment variable details","description":"Retrieves details of a single environment variable.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"},{"name":"envid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric environment variable ID"}],"responses":{"200":{"description":"Environment variable details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"env":{"$ref":"#/components/schemas/EnvironmentVariable"},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}},"patch":{"tags":["Environment Variables"],"summary":"Update environment variable","description":"Updates the name, value, or placeholder of a bot environment variable.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"},{"name":"envid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric environment variable ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"NEW_API_URL"},"value":{"type":"string","example":"https://newapi.example.com"},"placeholder":{"type":"string","example":"New integration endpoint"}}}}}},"responses":{"200":{"description":"Environment variable updated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Env variable updated successfully."},"env":{"$ref":"#/components/schemas/EnvironmentVariable"},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}},"delete":{"tags":["Environment Variables"],"summary":"Delete environment variable","description":"Removes the environment variable from the bot.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"},{"name":"envid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric environment variable ID"}],"responses":{"200":{"description":"Environment variable deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Env variable deleted successfully."},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}}},"/bot/{botid}/logs":{"get":{"tags":["Logs Management"],"summary":"List bot logs","description":"Retrieves output, activity, or error logs generated by the bot runtime.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"List of bot logs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"logs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"60c72b2f9b1d8a25c8d23456"},"bot_id":{"type":"integer","example":123456},"command":{"type":"string","example":"/start"},"error_message":{"type":"string","example":"Detailed error message description"},"stack":{"type":"string","example":"Error stack trace details"},"type":{"type":"string","example":"error"},"timezone":{"type":"string","example":"UTC"},"log_timestamp":{"type":"string","example":"2026-06-07 11:44:44"}}}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}},"delete":{"tags":["Logs Management"],"summary":"Clear bot logs","description":"Deletes all logs generated by this bot from the database.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"Logs cleared successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"All bot logs deleted successfully."},"deleted_count":{"type":"integer","example":5},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}}},"/bot/{botid}/analytics":{"get":{"tags":["Bot Analytics"],"summary":"Get bot analytics & statistics","description":"Retrieves aggregated statistics and health metrics (users, active sessions, message throughput) for the bot.","security":[{"cookieAuth":[]},{"apiKeyHeader":[]},{"bearerAuth":[]}],"parameters":[{"name":"botid","in":"path","required":true,"schema":{"type":"string"},"description":"The numeric bot ID"}],"responses":{"200":{"description":"Analytics payload retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"analytics":{"type":"object","properties":{"bot_id":{"type":"integer","example":123456},"total_users":{"type":"integer","example":100},"active_24h":{"type":"integer","example":10},"active_month":{"type":"integer","example":50},"new_month":{"type":"integer","example":30},"new_today":{"type":"integer","example":5},"premium_users":{"type":"integer","example":2},"private_chats":{"type":"integer","example":80},"group_chats":{"type":"integer","example":15},"channel_chats":{"type":"integer","example":5},"calculated_at":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"processing_time_ms":{"type":"number","example":10}}}}}}}}}}}}}}}