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 /v2 next 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 with 401. Wrong tokens are counted per client address (30 a minute, then 429).
  • Ids are UUIDs.
  • Errors are JSON, {"message": "...", "code": 10003}: 10003 unknown channel (also for a channel the bot may not see), 10008 unknown message, 50013 missing permissions, 50035 invalid form body, 50006 empty message, 40005 too large, 0 for plain HTTP errors.

Routes

RouteNeeds
GET /users/@mea valid token
GET /channelsthe 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}/messagesSend 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}/@meAdd 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/@originalinteractions
GET /gatewaythe 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

  • @username notifies members who can view the channel.
  • @all and @here only when the bot may mention everyone and allowed_mentions.parse contains "everyone".
  • @Role Name notifies the role's members when allowed_mentions.parse contains "roles", or allowed_mentions.roles lists 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_mentions mentions 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.

Something wrong on this page? Tell us.