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.

This page documents every REST endpoint exposed by the Dummy Gemini Bot admin server, including request parameters and response fields. All endpoints require Bearer authentication — see API Overview for authentication details.

​
Stats

​
GET /api/stats

Returns live database statistics and the most recent error log entries. Useful for monitoring bot health from the admin dashboard. No request parameters. Response fields:
​
total_messages
integer
Total number of messages stored across all chats in the database.
​
total_chats
integer
Number of distinct chats that have at least one message on record.
​
db_size_kb
float
Current size of the SQLite database file in kilobytes.
​
total_downloaded_bytes
integer
Cumulative bytes downloaded for media processing (yt-dlp, Telegram files, etc.) since the database was created.
​
total_uploaded_bytes
integer
Cumulative bytes uploaded to Telegram (sent media, voice messages, etc.) since the database was created.
​
recent_errors
array
The last 10 entries from the error_logs table. Each object contains:
  • timestamp — ISO datetime string of when the error occurred
  • type — short error category string (e.g. "TELEGRAM_API_ERROR")
  • message — human-readable error description
  • stack_trace — full Python traceback, if captured
Example response: 
{
  "total_messages": 4821,
  "total_chats": 12,
  "db_size_kb": 512.4,
  "total_downloaded_bytes": 1073741824,
  "total_uploaded_bytes": 524288000,
  "recent_errors": []
}

​
Configuration

​
GET /api/config

Returns all runtime configuration key-value pairs currently loaded from the config database table. No request parameters. Response: A flat JSON object with every config key as a property. The full set of default keys is defined in config.py’s DEFAULT_CONFIG, including MODEL_ID, CONTEXT_LIMIT, SYSTEM_INSTRUCTION, TTS_ENGINE, and others. Example response: 
{
  "MODEL_ID": "gemini-2.5-flash",
  "FALLBACK_MODELS": "gemini-2.5-flash-lite,gemini-2.5-flash,gemma-4-31b-it",
  "CONTEXT_LIMIT": "12",
  "TTS_ENGINE": "edge"
}

​
POST /api/config

Updates one or more configuration keys. Changes are persisted to the config table and take effect immediately in the running bot via the in-memory runtime_config dictionary. Request body (JSON): An object containing any subset of config keys as properties. Unrecognised keys are also stored — they are simply ignored by handlers that do not read them. Example request body: 
{ "MODEL_ID": "gemini-2.5-flash", "CONTEXT_LIMIT": "20" }
Response: 
{ "status": "success" }

​
Chats

​
GET /api/chats

Returns all rows from the chat_metadata table, ordered by last_active descending. Used by the admin dashboard to display and manage active conversations. No request parameters. Response: Array of chat objects, each with the following fields:
FieldTypeDescription
chat_idintegerTelegram chat ID
namestringChat or user display name
typestringChat type ("private", "group", "supergroup", "channel", or "unknown")
msg_countintegerTotal messages logged for this chat
last_activestringISO datetime of the most recent message
is_mutedinteger1 if the bot is muted in this chat, 0 otherwise
custom_roast_chancefloat | nullPer-chat random roast probability override
custom_cooldowninteger | nullPer-chat cooldown override in seconds
custom_tts_enginestring | nullPer-chat TTS engine override ("edge" or "gemini")
custom_modelstring | nullPer-chat Gemini model ID override
custom_system_instructionstring | nullPer-chat system prompt override
usernamestring | nullTelegram username of the chat or user
is_discussioninteger1 if the chat is in discussion (scientific/technical) mode

​
POST /api/chat/settings

Updates one or more settings for a specific chat. Only fields present in the request body are modified; omitted fields are left unchanged. Request body parameters:
​
chat_id
integer
required
Telegram ID of the target chat.
​
is_muted
integer
Set to 1 to mute the bot in this chat, 0 to unmute.
​
custom_roast_chance
float
Override the random roast probability for this chat (0.0–1.0). Pass an empty string "" to reset to the global default.
​
custom_cooldown
integer
Override the message cooldown for this chat in seconds. Pass an empty string "" to reset to the global default.
​
custom_tts_engine
string
Override the TTS engine for this chat. Accepted values: "edge" or "gemini". Pass an empty string "" to reset.
​
custom_model
string
Override the Gemini model ID used in this chat (e.g. "gemini-2.5-flash"). Pass an empty string "" to reset.
​
custom_system_instruction
string
Override the system instruction / persona prompt for this chat. Pass an empty string "" to reset.
​
is_discussion
integer
Set to 1 to enable discussion mode (scientific/technical tone), 0 to disable.
Response: 
{ "status": "success" }

​
POST /api/chat/leave

Instructs the bot to leave a group chat via the Telegram Bot API. Request body: 
{ "chat_id": 123456789 }
Response: 
{ "status": "success" }

​
POST /api/chat/alert

Sends a plain or Markdown-formatted message to a specific chat on behalf of the bot. Request body: 
{ "chat_id": 123456789, "message": "Alert text here" }
Response: 
{ "status": "success" }

​
GET /api/chat/top_users

Returns the top message senders for a given chat, ranked by message count. Query parameters:
ParameterTypeRequiredDescription
chat_idintegerYesTelegram chat ID to query
limitintegerNoNumber of results to return (default: 5)
Response: Array of user objects: 
[
  { "name": "Alice", "count": 342 },
  { "name": "Bob",   "count": 198 }
]

​
Moderation

​
GET /api/blocked

Returns all blocked users and groups stored in the blocked table. No request parameters. Response: Array of blocked-target objects: 
[
  { "id": 123456789, "type": "user",  "name": "spammer_joe" },
  { "id": -100987654, "type": "group", "name": "Bad Group" }
]

​
POST /api/block

Blocks a user or group by Telegram ID. If the target is a group (negative ID), the bot will also attempt to leave it automatically. Request body:
​
target_id
integer
required
Telegram user or chat ID to block.
​
type
string
Entity type — "user" or "group". Defaults to "unknown" if omitted.
​
name
string
Display name to show in the blocked list. Defaults to "Unknown" if omitted.
Response: 
{ "status": "success" }

​
POST /api/unblock

Removes a target from the block list. The bot will start responding to that user or group again on the next message. Request body: 
{ "target_id": 123456789 }
Response: 
{ "status": "success" }

​
GET /api/specials

Returns all VIP users who have a custom system instruction configured. No request parameters. Response: Array of VIP user objects: 
[
  { "username": "alice", "instruction": "Always respond formally to this user." }
]

​
POST /api/specials

Adds a new VIP user or updates the instruction for an existing one. The @ prefix is stripped from the username automatically. Request body:
​
username
string
required
Telegram username without the @ prefix.
​
instruction
string
required
Custom system instruction to inject when the bot is replying to this user.
Response: 
{ "status": "success" }

​
POST /api/specials/delete

Removes a VIP user and their custom instruction. Request body: 
{ "username": "john" }
Response: 
{ "status": "success" }

​
Broadcast

​
POST /api/broadcast

Sends a message to every chat ID recorded in the database. The bot first attempts to send with Markdown parse mode; if that fails it retries with plain text before marking the delivery as failed. Request body: 
{ "message": "Your broadcast text here" }
Response: 
{ "status": "success", "sent": 10, "total": 12 }
FieldTypeDescription
statusstring"success" or "error"
sentintegerNumber of chats that received the message
totalintegerTotal number of chats attempted

​
Tools

​
POST /api/upload_cookies

Uploads a new cookies.txt file used by yt-dlp for authenticated media downloads (e.g. age-restricted YouTube videos). The file is written to both the database directory and the project root. Request body (JSON):
​
cookies
string
required
Full text content of the Netscape-format cookies.txt file.
Response: 
{ "status": "success" }

​
POST /api/update_ytdlp

Upgrades yt-dlp to the latest version by running pip install --upgrade yt-dlp in a subprocess. No request body required. Response: 
{
  "status": "success",
  "output": "Successfully installed yt-dlp-2025.x.x"
}
On failure, returns HTTP 500 with a "reason" field containing the stderr output from pip.

​
Quota Monitoring

​
GET /api/model_limits

Returns per-model Gemini API request statistics derived from the api_requests_log table, along with model metadata fetched from the Gemini API. All models currently configured via MODEL_ID, FALLBACK_MODELS, and TTS_GEMINI_MODEL are included. No request parameters. Response: An object with two top-level keys:
  • models — array of model detail objects (one per active model), each containing:
FieldTypeDescription
model_idstringModel identifier as configured
display_namestringHuman-readable name from the Gemini API
descriptionstringModel description from the Gemini API
input_token_limitinteger | nullMax input tokens supported
output_token_limitinteger | nullMax output tokens supported
statusstring"active" or "error"
is_ttsbooleantrue if this model is used for TTS
errorstring | nullError message if the model could not be queried
limitsobjectConfigured rate limits: { "rpm": N, "tpm": N, "rpd": N }
usageobjectPer-model usage stats (see below)
  • usage — aggregate usage stats split by request type ("text" and "tts"), each with last_minute and last_24_hours buckets.
The usage object inside each model entry has this shape: 
{
  "last_minute":   { "requests": 3, "errors": 0 },
  "last_24_hours": { "requests": 847, "errors": 2 }
}
Example response: 
{
  "models": [
    {
      "model_id": "gemini-2.5-flash",
      "display_name": "Gemini 2.5 Flash",
      "description": "Fast, efficient multimodal model.",
      "input_token_limit": 1048576,
      "output_token_limit": 8192,
      "status": "active",
      "is_tts": false,
      "error": null,
      "limits": { "rpm": 15, "tpm": 1000000, "rpd": 1500 },
      "usage": {
        "last_minute":   { "requests": 3, "errors": 0 },
        "last_24_hours": { "requests": 847, "errors": 2 }
      }
    }
  ],
  "usage": {
    "text": {
      "last_minute":   { "requests": 3, "errors": 0 },
      "last_24_hours": { "requests": 847, "errors": 2 }
    },
    "tts": {
      "last_minute":   { "requests": 1, "errors": 0 },
      "last_24_hours": { "requests": 120, "errors": 0 }
    }
  }
}

​
POST /api/chat/send_profile_link

Sends the requesting admin a Telegram message containing an inline button that deep-links to a target user’s profile (tg://user?id=<target_id>). The message is sent directly to the authenticated admin’s Telegram DM. Request body:
​
target_id
integer
required
Telegram user ID whose profile link should be sent.
​
target_name
string
Display name to show on the inline button label (default: "User").
Response: 
{ "status": "success" }

Build docs developers (and LLMs) love

Get started for freeTalk to us