API Reference

Discord's API is based around two core layers, a HTTPS/REST API for general operations, and persistent secure WebSocket based connection for sending and subscribing to real-time events. The most common use case of the Discord API will be providing a service, or access to a platform through the OAuth2 API.

Base URL

Stable: https://discord.com/api
Canary: https://canary.discord.com/api

API Versioning

Discord exposes different versions of the API. You should specify which version to use by including it in the request path like https://discord.com/api/v{version_number}. Omitting the version number from the route will route requests to the current default version (marked below).

API Versions

Error Messages

Starting in API v7, form error responses have improved error formatting. The response will tell you which JSON key contains the error, the error code, and a human readable error message. Discord is frequently adding new error messages, so a complete list of errors is not feasible and would be almost instantly out of date. Here are some examples instead:

Array Error

{
  "code": 50035,
  "errors": {
    "activities": {
      "0": {
        "platform": {
          "_errors": [
            {
              "code": "BASE_TYPE_CHOICES",
              "message": "Value must be one of ('desktop', 'android', 'ios')."
            }
          ]
        },
        "type": {
          "_errors": [
            {
              "code": "BASE_TYPE_CHOICES",
              "message": "Value must be one of (0, 1, 2, 3, 4, 5)."
            }
          ]
        }
      }
    }
  },
  "message": "Invalid Form Body"
}

Object Error

{
  "code": 50035,
  "errors": {
    "access_token": {
      "_errors": [
        {
          "code": "BASE_TYPE_REQUIRED",
          "message": "This field is required"
        }
      ]
    }
  },
  "message": "Invalid Form Body"
}

Request Error

{
  "code": 50035,
  "message": "Invalid Form Body",
  "errors": {
    "_errors": [
      {
        "code": "APPLICATION_COMMAND_TOO_LARGE",
        "message": "Command exceeds maximum size (4000)"
      }
    ]
  }
}

Authentication

Authenticating with the Discord API can be done in one of two ways:

1. Using a user or bot token gained by logging into an account or registering a bot. For more information on users and bots, see bots vs user accounts.
2. Using an OAuth2 bearer token gained through the OAuth2 API.

For all authentication types, authentication is performed with the Authorization HTTP header in the format Authorization: TOKEN_TYPE? TOKEN.

Example User Token Authorization Header

Authorization: MTk4NjIyNDgzNDcxOTI1MjQ4.Cl2FMQ.ZnCjm1XVW7vRze4b7Cq4se7kKWs

Example Bot Token Authorization Header

Authorization: Bot MTk4NjIyNDgzNDcxOTI1MjQ4.Cl2FMQ.ZnCjm1XVW7vRze4b7Cq4se7kKWs

Example Bearer Token Authorization Header

Authorization: Bearer CZhtkLDpNYXgPH9Ml6shqh2OwykChw

Encryption

All HTTP-layer services and protocols (e.g. HTTP, WebSocket) within the Discord API are using TLS 1.2.

Snowflake Format

Discord utilizes Twitter's snowflake format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of Discord, except in some unique scenarios in which child objects share their parent's ID. Because Snowflake IDs are up to 64 bits in size (e.g. a uint64), they are always returned as strings in the HTTP API to prevent integer overflows in some languages. See the Gateway documentation for more information regarding Gateway encoding.

Snowflake ID Broken Down in Binary

111111111111111111111111111111111111111111 11111 11111 111111111111
64                                         22    17    12          0

Snowflake ID Format Structure (Left to Right)

Convert Snowflake to DateTime

Snowflake IDs in Pagination

Discord typically uses snowflake IDs in many API routes for pagination. The standardized pagination paradigm utilized is one in which you can specify IDs before and after in combination with limit to retrieve a desired page of results. You will want to refer to the specific endpoint documentation for details.

It is useful to note that snowflake IDs are just numbers with a timestamp, so when dealing with pagination where you want results from the beginning of time (in Discord Epoch, but 0 works here too) or before/after a specific time you can generate a snowflake ID for that time.

Generating a Snowflake ID from a Timestamp Example

(timestamp_ms - DISCORD_EPOCH) << 22

ID Serialization

There are some cases in which the API and Gateway may return IDs in an unexpected format. Internally, Discord stores IDs as integer snowflakes. When IDs are serialized to JSON, bigints are transformed into strings. Given that all Discord IDs are snowflakes, you should always expect a string.

However, there are cases in which passing something to the API will instead return IDs serialized as an integer; this is the case when you send the API or Gateway a value in an id field that is not bigint size. For example, when requesting GUILD_MEMBERS_CHUNK from the gateway:

// Send
{
  op: 8,
  d: {
    guild_id: [ '308994132968210433' ],
    user_ids: [ '123123' ]
  }
}

// Receive
{
  t: 'GUILD_MEMBERS_CHUNK',
  s: 3,
  op: 0,
  d: {
    not_found: [ 123123 ],
    members: [],
    guild_id: '308994132968210433'
  }
}

You can see in this case that the sent user_id is not a bigint; therefore, when it is serialized back to JSON by Discord, it is not transformed into a string. This will never happen with IDs that come from Discord. But, this can happen if you send malformed data in your requests.

ISO8601 Date/Time

Discord utilizes the ISO8601 format for most Date/Times returned in the API. This format is referred to as type ISO8601 within tables in this documentation.

Consistency

Discord operates at a scale where true consistency is impossible. Because of this, lots of operations in the API and in-between API services are eventually consistent. Due to this, client actions can never be serialized and may be executed in any order (if executed at all). Along with these constraints, events in Discord may:

• Never be sent to a client
• Be sent exactly one time to the client
• Be sent up to N times per client

Clients should operate on events and results from the API in as much of an idempotent behavior as possible.

HTTP API

User Agent

Clients using the HTTP API should provide a valid User Agent which specifies information about the client library and version in the following format:

User Agent Example

User-Agent: DiscordBot ($url, $versionNumber)

Clients may append more information and metadata to the end of this string as they wish.

Rate Limiting

The HTTP API implements a process for limiting and preventing excessive requests in accordance with RFC 6585. API users that regularly hit and ignore rate limits will have their API keys revoked, and be blocked from the platform. For more information on rate limiting of requests, please see the Rate Limits section.

Boolean Query Strings

Certain endpoints in the API are documented to accept booleans for their query string parameters. While there is no standard system for boolean representation in query string parameters, Discord represents such cases using True, true, or 1 for true and False, false or 0 for false.

Debugging

The HTTP API accepts an optional X-Debug-Options header with a comma-delimited list of debug options. The options in this list can be arbitrary, but the below options have effects:

APM Tracing

Discord offers an APM (Application Performance Monitoring) service that allows Discord employees to view traces of requests made to the API. This is useful for debugging issues with the API, and can be enabled by setting trace in the X-Debug-Options header as described above.

When tracing requests, you must provide an additional X-Client-Trace-ID header with a unique identifier for the request. This identifier can be generated with the following pseudocode:

import base64
import random
import struct
import time

class IDGenerator:
    def __init__(self):
        self.prefix = random.randint(0, 0xFFFFFFFF) & 0xFFFFFFFF
        self.creation_time = int(time.time() * 1000)
        self.sequence = 0

    def generate(self, user_id: int = 0):
        uuid = bytearray(24)
        # Lowest signed 32 bits
        struct.pack_into("<I", uuid, 0, user_id & 0xFFFFFFFF)
        struct.pack_into("<I", uuid, 4, user_id >> 32)
        struct.pack_into("<I", uuid, 8, self.prefix)
        # Lowest signed 32 bits
        struct.pack_into("<I", uuid, 12, self.creation_time & 0xFFFFFFFF)
        struct.pack_into("<I", uuid, 16, self.creation_time >> 32)
        struct.pack_into("<I", uuid, 20, self.sequence)
        self.sequence += 1
        return base64.b64encode(uuid).decode("utf-8")

if __name__ == "__main__":
    generator = IDGenerator()
    # Use 0 for user_id if you don't have one
    generator.generate(user_id or 0)

After the request is completed, the trace may be viewed by navigating to https://app.datadoghq.com/apm/traces?query=@guid.x-client-trace-id:"{trace_id}"&showAllSpans=true (replacing the {trace_id} with the value you provided).

Gateway API

Discord's Gateway API is used for maintaining persistent, stateful WebSocket connections between your client and Discord servers. These connections are used for sending and receiving real-time events your client can use to track and update local state. The Gateway API uses secure WebSocket connections as specified in RFC 6455. For information on opening Gateway connections, please see the Gateway API section.

Client Properties

Client properties, or "super properties", contain tracking information about the current client, used for analytics and A/B testing purposes. These properties are sent when identifying with the Gateway and are included with every outgoing HTTP request using the X-Super-Properties header as a base 64-encoded JSON object.

When these properties are not provided, Discord will attempt to parse some of them from the User-Agent header of requests.

Client Properties Structure

Due to the nature of client properties, the structure of this object is not well-defined, and no field is truly required. Additionally, types of fields are not verified, and all documented enums are merely conventions. Fields are marked as required if it's observed that they are sent in all official client properties.

¹ These properties are used to gate experimental features and may be required for certain endpoints. client_version is used instead of client_build_number for mobile experiments. See the experiments documentation for more information.

² If specified, this value should match the User-Agent header sent by the client.

Operating System Type

Browser Type

Client Event Source

Release Channel

Design ID

Accessibility Feature Flags

Search Engine

Example Client Properties (Web)

{
  "os": "Windows",
  "browser": "Chrome",
  "device": "",
  "system_locale": "en-US",
  "browser_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36 Edg/124.0.0.0",
  "browser_version": "124.0.0.0",
  "os_version": "10",
  "referrer": "https://www.reddit.com/",
  "referring_domain": "www.reddit.com",
  "referrer_current": "https://www.google.com/",
  "referring_domain_current": "www.google.com",
  "search_engine_current": "google",
  "mp_keyword_current": "discord",
  "release_channel": "stable",
  "client_build_number": 290453,
  "client_event_source": null,
  "has_client_mods": false
}

Example Client Properties (Windows)

{
  "os": "Windows",
  "browser": "Discord Client",
  "release_channel": "canary",
  "client_version": "1.0.341",
  "os_version": "10.0.26090",
  "os_arch": "x64",
  "app_arch": "x64",
  "system_locale": "en-US",
  "has_client_mods": false,
  "browser_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) discord/1.0.341 Chrome/120.0.6099.291 Electron/28.2.10 Safari/537.36",
  "browser_version": "28.2.10",
  "os_sdk_version": "26120",
  "client_build_number": 290668,
  "native_build_number": 47493,
  "client_event_source": null
}

Example Client Properties (macOS)

{
  "os": "Mac OS X",
  "browser": "Discord Client",
  "release_channel": "ptb",
  "client_version": "0.0.113",
  "os_version": "23.4.0",
  "os_arch": "arm64",
  "app_arch": "arm64",
  "system_locale": "en-US",
  "has_client_mods": false,
  "browser_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) discord/0.0.113 Chrome/120.0.6099.291 Electron/28.2.10 Safari/537.36",
  "browser_version": "28.2.10",
  "os_sdk_version": "23",
  "client_build_number": 290668,
  "native_build_number": null,
  "client_event_source": null
}

Example Client Properties (Linux)

{
  "os": "Linux",
  "browser": "Discord Client",
  "release_channel": "canary",
  "client_version": "0.0.381",
  "os_version": "5.15.153.1-microsoft-standard-WSL2",
  "os_arch": "x64",
  "app_arch": "x64",
  "system_locale": "en-US",
  "has_client_mods": false,
  "browser_user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) discord/0.0.381 Chrome/120.0.6099.291 Electron/28.2.10 Safari/537.36",
  "browser_version": "28.2.10",
  "window_manager": "Hyprland,unknown",
  "distro": "Ubuntu 22.04.4 LTS",
  "client_build_number": 290668,
  "native_build_number": null,
  "client_event_source": null
}

Example Client Properties (Android)

{
  "os": "Android",
  "browser": "Discord Android",
  "device": "a20e", // Samsung Galaxy A20e
  "system_locale": "en-US",
  "has_client_mods": false,
  "client_version": "227.6 - rn",
  "release_channel": "canaryRelease",
  "device_vendor_id": "17503929-a4b8-4490-87bf-0222adfdadc8",
  "browser_user_agent": "", // While it is not provided here, the User-Agent header is Discord-Android/227206;RNA
  "browser_version": "",
  "os_version": "34", // Android 14
  "client_build_number": 227206,
  "client_event_source": null,
}

Example Client Properties (iOS)

{
  "os": "iOS",
  "browser": "Discord iOS",
  "device": "iPhone14,5", // iPhone 13
  "system_locale": "en-US",
  "has_client_mods": false,
  "client_version": "227.0",
  "release_channel": "stable",
  "device_vendor_id": "AFF0710F-CEC0-4671-B2CF-0A03D72B5FD0",
  "browser_user_agent": "", // While it is not provided here, the User-Agent header is Discord/58755 CFNetwork/1494.0.7 Darwin/23.4.0
  "browser_version": "",
  "os_version": "17.4.1",
  "client_build_number": 58755,
  "client_event_source": null,
}

Message Formatting

Discord utilizes a subset of markdown for rendering message content on its clients, while also adding some custom functionality to enable things like mentioning users and channels. This functionality uses the following formats:

Formats

Using the markdown for either users, roles, or channels will usually mention the target(s) accordingly, but this can be suppressed using the allowed_mentions parameter when creating a message. Standard emoji are currently rendered using Twemoji for Desktop/Android and Apple's native emoji on iOS.

Timestamps are expressed in seconds and display the given timestamp in the user's timezone and locale.

¹ User mentions with an exclamation mark are deprecated and should be handled like any other user mention.

² Subcommands and subcommand groups can also be mentioned by using respectively </NAME SUBCOMMAND:ID> and </NAME SUBCOMMAND_GROUP SUBCOMMAND:ID>.

Timestamp Styles

¹ This is the default.

Guild Navigation Types

Guild navigation types link to the corresponding resource in the current guild.

CDN Formatting

CDN Base URL

https://cdn.discordapp.com/

Discord uses IDs and hashes to render images and other CDN content in the client. These hashes can be retrieved through various API requests, like Get User. Below are the formats, size limitations, and CDN endpoints for content in Discord. The returned format can be changed by changing the extension name at the end of the URL. For images, the returned size can be changed by appending a query string of ?size=desired_size to the URL. Image size can be any power of two between 16 and 4096, with some additional accepted values outlined below.

In the case of endpoints that support animated images, the hash will begin with a_ if it is available in APNG or GIF format (e.g. a_1269e74af4df7417b13759eae50c83dc).

File Formats

CDN Endpoints

¹ The value for user_index in the path for migrated users should be the user's ID shifted 22 bits to the left modulo 6 (i.e. user_id >> 22 % 6). The value for non-migrated users the user's discriminator modulo 5 (Test#1337 would be 1337 % 5, which evaluates to 2). The value for teams should be the team's ID modulo 5 (i.e. team_id % 5). See the section on Discord's new username system for more information.

² The size of images returned is constant with the size query string parameter being ignored.

³ The sticker will be available as PNG if its format_type is PNG or APNG, GIF if its format_type is GIF, and as Lottie if its format_type is LOTTIE. GIF stickers are not available through the CDN, and must be accessed at https://media.discordapp.net/stickers/{sticker_id}.gif.

⁴ The attachment will only be available in its uploaded format, which can be any format.

⁵ The theme path is only used for fetching the game_tile and logotype assets.

CDN Parameters

The CDN supports various query string parameters. These parameters are optional and can be used to modify the returned resource. Parameters are only applicable to image resources.

¹ The CDN only accepts boolean parameters as true or false (not 1 or 0).

Image Quality

The quality of the image to return. Only supported with images of type WebP and JPG (the rest are always lossless). The quality can be any of the following values:

Signed Attachment URLs

Attachments uploaded to Discord's CDN (like user-uploaded images) have signed URLs with a preset expiry time. This includes ephemeral attachments. Discord automatically refreshes attachment CDN URLs that appear within the client, so when you receive a payload with a signed URL (like when you fetch a message), it will be valid.

When passing CDN URLs into API fields, like url in an embed image object and avatar_url for webhooks, or when simply sending a message, you can pass the CDN URL without any parameters as the value and Discord will automatically render and refresh the URL.

If you need to refresh an attachment URL manually, you can use the Refresh Attachment URLs endpoint with any URL.

Other CDN endpoints listed above are not signed, so they will not expire.

Attachment URL Query Parameters

Example Attachment URL

https://cdn.discordapp.com/attachments/1012345678900020080/1234567891233211234/my_image.png?ex=65d903de&is=65c68ede&hm=2481f30dd67f503f54d020ae3b5533b9987fae4e55f2b4e3926e08a3fa3ee24f&

CDN Data

CDN data is a Data URI scheme that supports formats such as JPG, GIF, and PNG. An example Data URI format is:

data: image / jpeg;
base64, BASE64_ENCODED_JPEG_IMAGE_DATA;

Ensure you use the proper content type (e.g. image/jpeg, image/png, image/gif) that matches the image data being provided.

Uploading Files

Some endpoints support file attachments, indicated by the files[n] parameter. To add file(s), the standard application/json body must be replaced by a multipart/form-data body. The JSON message body can optionally be provided using the payload_json parameter.

All files[n] parameters must include a valid Content-Disposition subpart header with a filename and unique name parameter. Each file parameter must be uniquely named in the format files[n] such as files[0], files[1], or files[42]. The suffixed index n is the snowflake placeholder that can be used in the attachments field, which can be passed to the payload_json parameter (or Callback Data Payloads).

Images can also be referenced in embeds using the attachment://filename URL. The filename for these URLs must be ASCII alphanumeric with underscores, dashes, or dots. An example payload is provided below.

Editing Message Attachments

The attachments JSON parameter includes all files that will be appended to the message, including new files and their respective snowflake placeholders (referenced above). When making a PATCH request, only files listed in the attachments parameter will be appended to the message. Any previously-added files that aren't included will be removed.

Example Request Bodies (multipart/form-data)

Note that these examples are small sections of an HTTP request to demonstrate behaviour of this endpoint - client libraries will set their own form boundaries (boundary is just an example). For more information, refer to the multipart/form-data spec.

This example demonstrates usage of the endpoint without payload_json.

-boundary
Content-Disposition: form-data; name="content"
Hello, World!
-boundary
Content-Disposition: form-data; name="tts"
true
-boundary--

This example demonstrates usage of the endpoint with payload_json and all content fields (content, embeds, files[n]) set.

-boundary
Content-Disposition: form-data; name="payload_json"
Content-Type: application/json
{
  "content": "Hello, World!",
  "embeds": [{
    "title": "Hello, Embed!",
    "description": "This is an embedded message.",
    "thumbnail": {
      "url": "attachment://myfile.png"
    },
    "image": {
      "url": "attachment://mygif.gif"
    }
  }],
  "message_reference": {
    "type": 0,
    "channel_id": "233648473390448640",
    "message_id": "233648473390448641"
  },
  "attachments": [{
      "id": 0,
      "description": "Image of a cute little cat",
      "filename": "myfile.png"
  }, {
      "id": 1,
      "description": "Rickroll gif",
      "filename": "mygif.gif"
  }]
}
-boundary
Content-Disposition: form-data; name="files[0]"; filename="myfile.png"
Content-Type: image/png
[image bytes]
-boundary
Content-Disposition: form-data; name="files[1]"; filename="mygif.gif"
Content-Type: image/gif
[image bytes]
-boundary--

Using Attachments within Embeds

You can upload attachments when creating a message and use those attachments within your embed. To do this, you will want to upload files as part of your multipart/form-data body. Make sure that you're uploading files which contain a filename, as you will need to reference it in your payload.

Within an embed object, you can then set an image to use an attachment as its URL with the attachment scheme syntax: attachment://filename.png

For example:

{
  "embeds": [
    {
      "image": {
        "url": "attachment://screenshot.png"
      }
    }
  ]
}

Uploading to Google Cloud

You can upload large attachments quickly directly to Discord's Google Cloud storage bucket, using the Create Attachments endpoint to generate upload URLs, and sending each generated URL a PUT request with the intended attachment as the body.

When using Google Cloud uploads, the file upload size limit applies to individual files, rather than the entire request.

An example implementation in Python pseudocode would be:

import requests
import os

url = "https://discord.com/api/v10/channels/<channel_id>/attachments"

headers = {
    "Authorization": "Bot <bot_token>"
}

filename = "index.js"
size = os.stat(filename).st_size

json = {
    "files": [{
        "file_size": size,
        "filename": filename
    }]
}

r = requests.post(url, headers=headers, json=json)
r.raise_for_status()

upload = r.json()['attachments'][0]
with open(filename, "r") as f:
    data = f.read()
    r = requests.put(upload['upload_url'], data=data)
    r.raise_for_status()

upload_filename = upload['upload_filename']

Now, instead of sending the attachment again in a form body in the request, you can just send the upload_filename! For example:

{
  "content": "look at my cute cat!",
  "attachments": [
    {
      "id": "0",
      "filename": "cat.png",
      "uploaded_filename": "6a08e58a-265f-485a-8c85-5cd4df0edde0/cat.png"
    }
  ]
}

Locales

Documentation Reference

This documentation uses various conventions to describe the API. Here are some common conventions you may see:

Nullable and Optional Resource Fields

Resource fields that may contain a null value have types that are prefixed with a question mark. Resource fields that are optional have names that are suffixed with a question mark.

Example Nullable and Optional Fields

¹ May be unexpectedly null at 3:00 AM on Tuesdays for accounts created on June 23rd, 2017.

Field Limits

A best effort is made to document the limits of fields where possible (e.g. maximum length of a string, maximum number of array elements). These limits are not exhaustive and may not cover all edge cases.

A fallback limit of 1521 array elements and 152133 characters is used when no well-defined limit exists.

Deprecated/Removed Fields

Fields that are deprecated will be marked with a (deprecated) notice next to them. Fields that are removed (and are kept for completion's sake, such as in enums) will be marked with strikethrough.

Event Fields

Certain fields are only present in structures received over the Gateway. These fields will usually be documented in the Gateway section instead of the main structure.

Badges

Certain endpoints may have badges that describe additional behavior in short form. Here are some examples you may find:

MFA Required

This endpoint may require that users with multi-factor authentication enabled authenticate themselves for certain actions. See the MFA verification documentation for implementation.

This is not applicable to OAuth2 and bot requests.

Audit Log Reason

The endpoint may be used with a X-Audit-Log-Reason header. This header is used to provide a reason for the action being performed. This reason will be shown in the audit log entry for this action. See the audit log documentation for more information.

Unauthenticated Request

These requests do not require the Authorization header to be present.

OAuth2 Request

The endpoint may be used with a bearer token in the Authorization header. The specific scope required (if any) will be provided if you hover over the badge.

Deprecated Endpoint

This endpoint remains active and functionally the same, but it should be avoided if possible as it may be removed in a future API version.