Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 37 ยท Bot Concepts and APIs

Discord REST API and Snowflakes

Learn how the Discord REST API identifies things with snowflake ids, encodes permissions as bitfields, and limits request rates with buckets and headers, with runnable BigInt and rate-limit examples.

Discord's REST API is the "do something" side of a bot: send and edit messages, manage roles, create channels, ban users, register commands. It is a conventional HTTP API with three concepts you must understand before anything else works smoothly: snowflake ids, permission bitfields and rate-limit buckets. None of them is hard, but each one has a JavaScript-specific trap.

Resources and routes

URLs follow the object hierarchy. A few you will meet often (base https://discord.com/api/v10):

Route Purpose
GET /users/@me The bot's own user
GET /guilds/{guild.id} A server
GET /guilds/{guild.id}/channels Channels of a server
POST /channels/{channel.id}/messages Send a message
PATCH /channels/{channel.id}/messages/{message.id} Edit a message
DELETE /channels/{channel.id}/messages/{message.id} Delete a message
PUT /guilds/{guild.id}/bans/{user.id} Ban a member
PUT /applications/{app.id}/commands Replace the global slash commands
POST /interactions/{id}/{token}/callback Answer an interaction

Responses are JSON objects whose fields are snake_case. Libraries such as discord.js convert them into camelCase classes, but the wire format is what the API reference documents.

Snowflakes

Every object has an id that is a snowflake: a 64-bit integer packing a creation time, a worker id and a counter. Because the timestamp sits in the high bits, snowflakes sort in creation order, and you can tell when anything was created from its id alone.

The layout (bit 0 is the least significant):

  • bits 22 and up: milliseconds since the Discord epoch, 2015-01-01T00:00:00Z (1420070400000 in Unix milliseconds)
  • bits 17 to 21: internal worker id
  • bits 12 to 16: internal process id
  • bits 0 to 11: increment, a counter per process

JavaScript numbers are 64-bit floating point and cannot represent every 64-bit integer, so a snowflake must be handled as a string or a BigInt.

Node.js Decoding and building snowflakes with BigInt

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Practical uses: show "account created" times, delete messages older than a given moment by comparing ids, and paginate with before and after parameters that take a snowflake. The makeSnowflake function lets you build a "fake id for time T" to use as a pagination cursor.

Permission bitfields

Permissions are a bitfield: each permission is one bit, and a role's permissions are the OR of all its bits, sent as a string of a decimal number (because it exceeds 32 bits, and in recent API versions even 53 bits). Some values:

Permission Bit Value
CREATE_INSTANT_INVITE 0 1
KICK_MEMBERS 1 2
BAN_MEMBERS 2 4
ADMINISTRATOR 3 8
MANAGE_CHANNELS 4 16
MANAGE_GUILD 5 32
VIEW_CHANNEL 10 1024
SEND_MESSAGES 11 2048
MANAGE_MESSAGES 13 8192
EMBED_LINKS 14 16384
MANAGE_ROLES 28 268435456

ADMINISTRATOR overrides everything, which is why you rarely give it to bots. Always use BigInt for bit operations: JavaScript's | and & operators on ordinary numbers truncate to 32 bits.

Node.js Permissions as BigInt bit flags

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Note the pattern (field & flag) === flag to test a bit, | to add and & ~flag to remove. Channel-level overwrites (allow and deny bitfields per role or member) layer on top of role permissions; the full resolution order is in the Discord documentation, but for now remember that an effective permission is computed, not stored.

Rate limits and buckets

Discord applies limits per route bucket: sending messages to one channel has a separate budget from banning members. Every response includes headers that describe your budget:

Header Meaning
X-RateLimit-Limit Requests allowed in the window
X-RateLimit-Remaining Requests left
X-RateLimit-Reset-After Seconds until the window resets (decimal)
X-RateLimit-Bucket An opaque bucket id; routes may share one
Retry-After and X-RateLimit-Global On a 429: wait this long, and whether the limit is global

There is also a global limit (around 50 requests per second per bot). A well-behaved client reads the headers and slows itself down before it gets a 429, because repeated 429s can lead to a temporary ban of your IP. The stand-in server below imitates a bucket that allows two requests per window.

Node.js A client that obeys X-RateLimit headers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Because the client waits when remaining reaches zero, no request is ever rejected. libraries like discord.js do this for you with per-bucket queues. If you build your own client, key your queue by bucket id (or by route plus the major parameter: channel id, guild id or webhook id) rather than using a single global queue.

Audit-log reasons

Moderation routes accept an X-Audit-Log-Reason header (URL-encoded) that appears in the server's audit log. Always set it when your bot bans, kicks or deletes on a user's behalf, so that admins can see why the bot acted.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why must snowflake ids be handled as strings or BigInt in JavaScript?

    Number is a 64-bit float with 53 bits of integer precision, so large ids would be silently rounded.
  2. 2. How do you read the creation time out of a snowflake?

    The upper bits hold milliseconds since 2015-01-01. Shift right 22 and add 1420070400000.
  3. 3. How do you check that a permission bitfield contains a flag?

    Bitwise AND with the flag leaves the flag bit set only when it was present.
  4. 4. What should a client do when X-RateLimit-Remaining is 0?

    Waiting proactively avoids 429 responses, which can escalate into temporary bans.

Summary

  • Discord REST routes follow the object hierarchy; JSON fields are snake_case.
  • Snowflakes encode creation time, worker, process and counter; keep them as strings or BigInt.
  • Permissions are string-encoded bitfields: test with (field & flag) === flag, add with |, remove with & ~flag, always with BigInt.
  • Rate limits apply per route bucket; read X-RateLimit-* headers, wait when remaining hits zero, and honour Retry-After on 429.
  • Send an audit-log reason with moderation actions.

Next: Discord Gateway and Intents