Conventions
- Versioned URL:
/api/v1/.... Breaking changes only ship in a new version. - IDs: UUID v7 strings. Paginate with
before/afterids (they are time ordered). - Dates: ISO 8601. Fields: camelCase. Permissions: big integer as a string (bitfield).
- Errors:
{ code, message, status }with stable string codes; see rate limits and errors. - Invisible means 404: a channel or server the bot can’t see answers as if it didn’t exist.
- User-Agent recommended:
FalafyBot (https://your.site, 1.0).
Routes
| Method | Route (/api/v1) | Auth | What it does |
|---|---|---|---|
GET | /users/@me | Bot · Bearer identify | The token’s user (email only with the email scope). |
GET | /users/@me/servers | Bot · Bearer servers | Servers of the user/bot with its permissions. |
GET | /users/{userId} | Bot | Public profile of someone who shares a server with the bot. |
POST | /users/@me/channels | Bot | Opens (or returns) a DM: { recipientId }. |
DELETE | /users/@me/servers/{serverId} | Bot | The bot leaves the server. |
GET | /oauth2/@me | Bearer | Application, scopes and expiry of the OAuth2 token. |
GET | /applications/@me | Bot | The bot’s application (public key, enabled intents). |
GET | /gateway/bot | Bot | Gateway URL and heartbeat interval. |
GET | /servers/{serverId} | Bot | Server data. |
GET | /servers/{serverId}/channels | Bot | Channels the bot can see. |
GET | /servers/{serverId}/roles | Bot | Server roles. |
GET | /servers/{serverId}/members | Bot + SERVER_MEMBERS | Members (limit up to 1000, after=userId). |
GET | /servers/{serverId}/members/{userId} | Bot | One member. |
PUT | /servers/{serverId}/members/{userId}/roles/{roleId} | Bot | Adds a role (manage roles + hierarchy). |
DELETE | /servers/{serverId}/members/{userId}/roles/{roleId} | Bot | Removes a role. |
GET | /channels/{channelId} | Bot | Channel data. |
GET | /channels/{channelId}/messages | Bot | History (limit, before, after). |
POST | /channels/{channelId}/messages | Bot | Sends: content, embeds, components, replyToId, mentions. |
GET | /channels/{channelId}/messages/{messageId} | Bot | One message. |
PATCH | /channels/{channelId}/messages/{messageId} | Bot | Edits one of the bot’s messages. |
DELETE | /channels/{channelId}/messages/{messageId} | Bot | Deletes (its own, or any with manage messages). |
PUT | /channels/{channelId}/messages/{messageId}/reactions/{emoji}/@me | Bot | Reacts. |
DELETE | /channels/{channelId}/messages/{messageId}/reactions/{emoji}/@me | Bot | Removes the reaction. |
GET | /channels/{channelId}/messages/{messageId}/reactions/{emoji} | Bot | Who reacted (up to 100). |
POST | /channels/{channelId}/typing | Bot | Shows “typing…”. |
GET | /channels/{channelId}/webhooks | Bot | Channel webhooks (manage webhooks). |
POST | /channels/{channelId}/webhooks | Bot | Creates a webhook: { name }. |
GET · PATCH · DELETE | /webhooks/{webhookId} | Bot | Manages a webhook. |
GET · PUT · POST | /applications/{appId}/commands | Bot | Global commands (PUT replaces all). |
GET · PATCH · DELETE | /applications/{appId}/commands/{commandId} | Bot | One global command. |
GET · PUT · POST | /applications/{appId}/servers/{serverId}/commands | Bot | One server’s commands (instant). |
POST | /interactions/{id}/{token}/callback | token | Initial interaction response. |
GET · PATCH · DELETE | /webhooks/{appId}/{token}/messages/@original | token | The original response. |
POST | /webhooks/{appId}/{token} | token | Follow-up. |
POST | /webhooks/{webhookId}/{token} | token | Executes a webhook (?wait=true). |
GET · PATCH · DELETE | /webhooks/{webhookId}/{token}/messages/{messageId} | token | Webhook message. |
Messages with embeds and components
Bots can send up to 10 embeds (title up to 256 characters, description up to 4096, up to 25 fields, 6000 characters in total) and up to 5 component rows. Embed images must be https; the app shows a link to them instead of loading images from other sites.
{
"content": "Topa uma partida?",
"components": [
{ "type": 1, "components": [
{ "type": 2, "style": 3, "label": "Bora", "customId": "aceitar" },
{ "type": 2, "style": 5, "label": "Regras", "url": "https://exemplo.com/regras" }
]},
{ "type": 1, "components": [
{ "type": 3, "customId": "jogo", "placeholder": "Qual jogo?",
"options": [{ "label": "CS2", "value": "cs2" }, { "label": "Valorant", "value": "val" }] }
]}
]
}Message content
Without the privileged MESSAGE_CONTENT intent, API reads and gateway events come with empty content, embeds, attachments and components, except in DMs, on the bot’s own messages and on messages that mention the bot.