The RESTÂ API
A separate, versioned path with a stable contract, served by the same handlers as the app: a bot can never do through the API what its permissions would not allow in the app.
Basics
- Base path:
/api/bot/v1. A breaking change gets/v2next to it. - Authentication:
Authorization: Bot <token>only. No cookie is read, so there is no CSRF path, and a bot token is refused on every other route with401. Wrong tokens are counted per client address (30 a minute, then429). - Ids are UUIDs.
- Errors are JSON,
{"message": "...", "code": 10003}:10003unknown channel (also for a channel the bot may not see),10008unknown message,50013missing permissions,50035invalid form body,50006empty message,40005too large,0for plain HTTP errors.
Routes
| Route | Needs |
|---|---|
GET /users/@me | a valid token |
GET /channels | the channels the bot can view, with their categories |
GET /channels/{id}/messages (limit, before, after, around) | View channels |
GET /channels/{id}/messages/{id} | View channels |
POST /channels/{id}/messages | Send messages; body content, embeds, components, allowed_mentions, message_reference, parent_id, lifetime_seconds (timed messages) |
PATCH /channels/{id}/messages/{id} | Send messages, own messages only; content, components, allowed_mentions |
DELETE /channels/{id}/messages/{id} | own messages; others' with Manage messages |
PUT, DELETE /channels/{id}/messages/{id}/reactions/{emoji}/@me | Add reactions (taking back always works) |
POST /channels/{id}/upload (multipart file, optional content, allowed_mentions, parent_id, reply_to_id) | Send messages and Attach files |
GET /media/{id} | View channels for a channel attachment, or membership of the direct message; streams the file, and answers 404 (never 403) for one the bot cannot view |
GET /members, GET /members/{id} | the GUILD_MEMBERS intent; only members who can view a channel the bot can view |
GET, PUT, POST /commands, DELETE /commands/{id} | slash commands |
POST /interactions/{id}/{token}/callback, .../followups, .../messages/@original | interactions |
GET /gateway | the gateway address, heartbeat interval and connection cap |
Every route with every field and response is in the REST reference, generated from the server's OpenAPI document.
Slow mode
A channel's slow mode holds a bot back like a member, on every route that posts (a message, an upload, the response to a command): a post inside the wait answers 429 with retry_after. A bot whose roles give it Manage messages is exempt.
Mentions
@usernamenotifies members who can view the channel.@alland@hereonly when the bot may mention everyone andallowed_mentions.parsecontains"everyone".@Role Namenotifies the role's members whenallowed_mentions.parsecontains"roles", orallowed_mentions.roleslists the role's id. A bot may mention roles marked mentionable; with Mention @all and @here it may mention any custom role.- Role mentions are off by default. A message without
allowed_mentionsmentions no role, and an edit without it removes role mentions instead of adding them.
The upload route takes the same object as the form field allowed_mentions, JSON-encoded.
Emoji
Custom emoji travel as the token the app stores, <:name:id> (copy one from a message you read). A plain :name: in a message posted through the API stays literal text. Unicode emoji work as typed.
Moderation applies to bots
A bot is a member for moderation too. A timed-out bot keeps reading but cannot post, react, attach files or answer commands (403, code 50013); its gateway stays open. A banned bot is refused like an unknown token (401), and its gateway sessions close at once with 4004.