Developer Portal
Platform Features

Bot API Reference

The Bot API provides direct, low-latency access to manage servers, fetch members, and interact with text channels. This is the core interface for building powerful server automations.

Base API Endpoint

https://modvc.org/api/bot

Authentication & Security

All requests require an Authorization header containing your bot's secret token. This token grants administrative privileges based on the roles assigned to your bot in the server.

// WARNING: NEVER SHARE YOUR TOKEN. DO NOT EXPOSE IT IN CLIENT CODE.Authorization: Bot m_bot_Vb2ptJVRTfNt7aeYtMivyzYayPSSHzxGTyOcttw...

Rate Limits

To prevent abuse and ensure stability for all bots, the ModVC API enforces rate limits. A standard Token Bucket algorithm is used.

  • Limit: 60 requests per minute per bot token.
  • Response: Exceeding this limit will result in a 429 Too Many Requests HTTP status code.
  • Header: The response will include a Retry-After header indicating the number of seconds until your limit resets.

Endpoint Dictionary

GET/?serverId={id}&type=members

Retrieves a comprehensive list of all members currently residing in the server, including their assigned roles and join dates.

Response Shape

{ "success": true, "members": [ { "uid": "wWngsi5euQPd...", "displayName": "Ashesh Das", "photoURL": "https://...", "role": "admin", "joinedAt": 1765038892000 } ] }
POST/ (action: get_messages)

Retrieves a list of recent messages from a specific text channel. Requires the bot to have the READ_MESSAGES permission in the server.

Request Body Payload

{ "action": "get_messages", "server_id": "SERVER_ID", "channel_id": "CHANNEL_ID", "limit": 50 }

Response Shape

{ "success": true, "messages": [ { "id": "msg_123...", "content": "Hello World!", "sender_name": "Ashesh", "created_at": 1765038892000 } ] }
POST/ (action: create_message)

Sends a message to a specific text channel. Supports rich text embeds and interactive UI components (like Buttons) that trigger Webhooks.

Request Body Payload

{ "action": "create_message", "server_id": "nzqb4EpU...", "channel_id": "ticket-ashesh-992", "content": "Welcome to your support ticket!", "embeds": [ { "title": "Support Request", "description": "Please describe your issue.", "color": "#EF4444" } ], "components": [ { "type": "button", "style": "danger", "label": "Close Ticket", "custom_id": "close_ticket" } ] }
POST/ (action: delete_message)

Deletes a specific message. If the bot is deleting another user's message, it must have the MANAGE_MESSAGES permission.

Request Body Payload

{ "action": "delete_message", "server_id": "SERVER_ID", "message_id": "MESSAGE_ID" }
POST/ (action: add_reaction)

Adds an emoji reaction to a specific message. Requires the ADD_REACTIONS permission.

Request Body Payload

{ "action": "add_reaction", "server_id": "SERVER_ID", "message_id": "MESSAGE_ID", "emoji": "👍" }
POST/ (action: delete_channel)

Permanently deletes a channel from the server. This is often used by Ticket Bots to cleanly close resolved support tickets.

Permission RequirementBot must possess the MANAGE_CHANNELS permission role in the server to execute this action.

Request Body Payload

{ "action": "delete_channel", "server_id": "nzqb4EpU...", "channel_id": "ticket-ashesh-992" }
POST/ (action: list_emojis)

Retrieves a list of all custom emojis registered under the specified server.

Request Body Payload

{ "action": "list_emojis", "server_id": "nzqb4EpU..." }

Response Shape

{ "success": true, "emojis": [ { "id": "emoji_123...", "name": "kekw", "url": "https://pub-...", "serverId": "nzqb4EpU...", "uploaderId": "bot_xyz...", "createdAt": 1765038892000 } ] }
POST/ (action: upload_emoji)

Uploads a new custom emoji to the server. The image payload can be an HTTP/HTTPS image URL or a base64 string (including base64 data URLs).

Requirements & Limits- Bot must possess the MANAGE_EMOJIS permission.
- Max emoji size is 256KB.
- Max 50 custom emojis per server.

Request Body Payload

{ "action": "upload_emoji", "server_id": "nzqb4EpU...", "name": "kekw", "image": "data:image/png;base64,iVBORw0KGgoAAAANS..." // or "https://example.com/image.png" }

Response Shape

{ "success": true, "emoji": { "id": "emoji_123...", "name": "kekw", "url": "https://pub-...", "serverId": "nzqb4EpU...", "uploaderId": "bot_xyz...", "createdAt": 1765038892000 } }
POST/ (action: delete_emoji)

Permanently deletes a custom emoji from the server.

Permission RequirementBot must possess the MANAGE_EMOJIS permission role in the server.

Request Body Payload

{ "action": "delete_emoji", "server_id": "nzqb4EpU...", "emoji_id": "emoji_123..." }
POST/ (action: presence)

Sends a heartbeat to the Edge Presence API to mark the bot as "Online". Bots must ping this endpoint every 15-30 seconds to maintain a green online status dot in the UI.

Request Body Payload

{ "action": "presence" }