Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AmiraliNotFound/dummy-gemini-bot/llms.txt

Use this file to discover all available pages before exploring further.

The admin REST API is an aiohttp server running on port 8080, powering the React admin dashboard. Every endpoint requires Telegram WebApp authentication — unauthenticated or unauthorized requests are rejected before any handler logic runs.

​
Base URL

http://localhost:8080
When deploying to a VPS or cloud host, substitute localhost with the domain set in WEBAPP_URL. HTTPS is required in production — Telegram Mini Apps will refuse to load resources over plain HTTP from non-localhost origins.

​
Authentication

All requests must include the following header: 
Authorization: Bearer <telegram_webapp_init_data>
<telegram_webapp_init_data> is the raw URL-encoded string exposed by the Telegram Mini App JavaScript SDK as window.Telegram.WebApp.initData.

​
How validation works

The server’s check_auth() function performs three checks in order:
  1. HMAC signature — The init data string is validated using HMAC-SHA256. The secret key is derived as: 
    secret_key = HMAC-SHA256(key=b"WebAppData", msg=TELEGRAM_TOKEN)
    The hash field embedded in the init data must match the HMAC of the sorted data-check string computed with that secret key.
  2. Session expiry — The auth_date field in the init data must be within 86400 seconds (24 hours) of the current server time. Older tokens are rejected to prevent replay attacks.
  3. Admin allowlist — The user.username decoded from the init data must appear (case-insensitively) in the ALLOWED_ADMINS environment variable. Users not on the list receive 403 Forbidden.

​
Example request

curl -H "Authorization: Bearer <init_data>" \
  http://localhost:8080/api/stats

​
DEV_BYPASS

Setting DEV_BYPASS=true in your .env file skips all authentication checks and returns a dummy admin ID. This is intended only for local development. Never enable DEV_BYPASS in a production environment.

​
Response Format

All endpoints return JSON. Successful responses include a status field (either "ok" or "success") along with any relevant data payload. Error responses follow this shape: 
{
  "status": "error",
  "reason": "Human-readable description of what went wrong"
}
Common HTTP status codes returned on error:
CodeMeaning
401Missing, empty, or cryptographically invalid Authorization header
403Valid signature but the user is not in ALLOWED_ADMINS
500Unexpected server-side or Telegram Bot API error

​
CORS

The server is configured with aiohttp-cors. The allowed origin is read from the WEBAPP_URL environment variable at startup:
  • If WEBAPP_URL is set, only requests from that exact origin are accepted.
  • If WEBAPP_URL is not set, the origin defaults to * (all origins).
In production, WEBAPP_URL should be set to the domain of your admin Mini App so that only that origin can call the API.

​
Available Endpoints

MethodPathDescription
GET/api/statsDatabase stats, bandwidth usage, recent errors
GET/api/configAll runtime configuration keys
POST/api/configUpdate one or more config keys
GET/api/chatsRecently active chats with metadata
POST/api/chat/settingsUpdate per-chat settings
POST/api/chat/leaveBot leaves a chat
POST/api/chat/alertSend alert to a chat
GET/api/chat/top_usersTop message senders in a chat
GET/api/blockedAll blocked users and groups
POST/api/blockBlock a user or group
POST/api/unblockUnblock a user or group
GET/api/specialsAll VIP users and instructions
POST/api/specialsAdd or update a VIP user
POST/api/specials/deleteRemove a VIP user
POST/api/broadcastBroadcast message to all chats
POST/api/upload_cookiesUpload yt-dlp cookies.txt
POST/api/update_ytdlpTrigger yt-dlp upgrade
GET/api/model_limitsPer-model RPM/RPD usage stats
POST/api/chat/send_profile_linkSend profile link to DM user
For full parameter and response documentation for every endpoint, see the API Endpoints reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us