> ## Documentation Index
> Fetch the complete documentation index at: https://docs.discord.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> The Discord API is a REST API that allows you to interact with Discord data from your own applications. It's the primary way to interact with Discord from your own code.

export const Snowflake = () => {
  return <div className="MDXSnowflake">
      <svg width="633" height="355" viewBox="0 0 633 355" fill="none" xmlns="http://www.w3.org/2000/svg">
        <text fontSize="20" fontWeight="bold">
          <tspan x="209" y="16.8223">
            175928847299117063
          </tspan>
        </text>
        <text fill="#252525" className="header">
          <tspan x="149" y="199.258">
            41944705796
          </tspan>
        </text>
        <text fill="#252525" className="header">
          <tspan x="140" y="276.258">
            1462015105796
          </tspan>
        </text>
        <text fill="#252525" className="header">
          <tspan x="72" y="350.258">
            2016-04-30 11:18:25.796 UTC
          </tspan>
        </text>
        <text fill="#343B8F" className="header group1">
          <tspan x="2" y="96.2578">
            000000100111000100000110010110101100000100
          </tspan>
        </text>
        <text fill="#8F2022" className="header group2">
          <tspan x="409" y="96.2578">
            00001
          </tspan>
        </text>
        <text fill="#1A6334" className="header group3">
          <tspan x="460" y="96.2578">
            00000
          </tspan>
        </text>
        <text fill="#252525" fontSize="12">
          <tspan x="326" y="54.1934">
            to binary
          </tspan>
        </text>
        <text fill="#252525" fontSize="12">
          <tspan x="215" y="154.193">
            to decimal
          </tspan>
        </text>
        <text fill="#252525" fontSize="12">
          <tspan x="215" y="312.193">
            Parse unix timestamp (ms)
          </tspan>
        </text>
        <text fill="#252525" fontSize="12">
          <tspan x="288.344" y="230.193">
            + 1420070400000
          </tspan>
          <tspan x="216.273" y="244.193">
            Discord Epoch (unix timestamp in ms)
          </tspan>
        </text>
        <text fill="#343B8F" fontSize="12">
          <tspan x="39.7383" y="114.193">
            Number of milliseconds since the Discord epoch{' '}
          </tspan>
          <tspan x="122.619" y="128.193">
            (first seconds of 2015)
          </tspan>
        </text>
        <text fill="#8F2022" fontSize="11">
          <tspan x="406.074" y="113.927">
            Internal
          </tspan>
          <tspan x="412.681" y="125.927">
            worker
          </tspan>
          <tspan x="425.894" y="137.927">
            ID
          </tspan>
        </text>
        <text fill="#1A6334" fontSize="11">
          <tspan x="461.074" y="113.927">
            Internal
          </tspan>
          <tspan x="464.377" y="125.927">
            process
          </tspan>
          <tspan x="480.894" y="137.927">
            ID
          </tspan>
        </text>
        <text className="header group4" fill="#0051B6">
          <tspan x="511" y="96.2578">
            000000000111
          </tspan>
        </text>
        <text fill="#0051B6" fontSize="12">
          <tspan x="524.861" y="114.193">
            Incremented{' '}
          </tspan>
          <tspan x="532.068" y="128.193">
            for every{' '}
          </tspan>
          <tspan x="521.258" y="142.193">
            generated ID{' '}
          </tspan>
          <tspan x="539.275" y="156.193">
            on that{' '}
          </tspan>
          <tspan x="539.275" y="170.193">
            process
          </tspan>
        </text>
        <text fill="#252525" fontSize="12">
          <tspan x="0" y="71.1934">
            64
          </tspan>
        </text>
        <text fill="#252525" fontSize="12">
          <tspan x="401" y="71.1934">
            22
          </tspan>
        </text>
        <text fill="#252525" fontSize="12">
          <tspan x="504" y="71.1934">
            12
          </tspan>
        </text>
        <text fill="#252525" fontSize="12">
          <tspan x="625" y="71.1934">
            0
          </tspan>
        </text>
        <text fill="#252525" fontSize="12">
          <tspan x="449" y="71.1934">
            17
          </tspan>
        </text>
        <path className="arrow" d="M316.646 73.3536C316.842 73.5488 317.158 73.5488 317.354 73.3536L320.536 70.1716C320.731 69.9763 320.731 69.6597 320.536 69.4645C320.34 69.2692 320.024 69.2692 319.828 69.4645L317 72.2929L314.172 69.4645C313.976 69.2692 313.66 69.2692 313.464 69.4645C313.269 69.6597 313.269 69.9763 313.464 70.1716L316.646 73.3536ZM316.5 31L316.5 73L317.5 73L317.5 31L316.5 31Z" fill="black"></path>
        <path className="arrow" d="M202.646 173.354C202.842 173.549 203.158 173.549 203.354 173.354L206.536 170.172C206.731 169.976 206.731 169.66 206.536 169.464C206.34 169.269 206.024 169.269 205.828 169.464L203 172.293L200.172 169.464C199.976 169.269 199.66 169.269 199.464 169.464C199.269 169.66 199.269 169.976 199.464 170.172L202.646 173.354ZM202.5 131V173H203.5V131H202.5Z" fill="black"></path>
        <path className="arrow" d="M201.646 256.354C201.842 256.549 202.158 256.549 202.354 256.354L205.536 253.172C205.731 252.976 205.731 252.66 205.536 252.464C205.34 252.269 205.024 252.269 204.828 252.464L202 255.293L199.172 252.464C198.976 252.269 198.66 252.269 198.464 252.464C198.269 252.66 198.269 252.976 198.464 253.172L201.646 256.354ZM201.5 214L201.5 256L202.5 256L202.5 214L201.5 214Z" fill="black"></path>
        <path className="arrow" d="M201.646 331.354C201.842 331.549 202.158 331.549 202.354 331.354L205.536 328.172C205.731 327.976 205.731 327.66 205.536 327.464C205.34 327.269 205.024 327.269 204.828 327.464L202 330.293L199.172 327.464C198.976 327.269 198.66 327.269 198.464 327.464C198.269 327.66 198.269 327.976 198.464 328.172L201.646 331.354ZM201.5 289L201.5 331L202.5 331L202.5 289L201.5 289Z" fill="black"></path>
      </svg>
    </div>;
};

export const ManualAnchor = ({id}) => {
  return <div className="MDXManualAnchor" id={id}></div>;
};

**Base URL**

```bash theme={"system"}
https://discord.com/api
```

## API Versioning

<Danger>
  Some API and Gateway versions are now non-functioning, and are labeled as discontinued in the table below for posterity. Trying to use these versions will fail and return 400 Bad Request.
</Danger>

Discord exposes different versions of our API[.](https://c.tenor.com/BuZl66EegkgAAAAC/westworld-dolores.gif) 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). You can find the change log for the newest API version [here](/developers/change-log).

<ManualAnchor id="api-versioning-api-versions" />

**API Versions**

| Version | Status       | Default                                |
| ------- | ------------ | -------------------------------------- |
| 10      | Available    |                                        |
| 9       | Available    |                                        |
| 8       | Deprecated   |                                        |
| 7       | Deprecated   |                                        |
| 6       | Deprecated   | <Icon icon="check" iconType="solid" /> |
| 5       | Discontinued |                                        |
| 4       | Discontinued |                                        |
| 3       | Discontinued |                                        |

## Error Messages

Starting in API v8, we've improved error formatting in form error responses. The response will tell you which JSON key contains the error, the error code, and a human readable error message. We will be 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**

```json theme={"system"}
{
  "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**

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

**Request Error**

```json theme={"system"}
{
  "code": 50035,
  "message": "Invalid Form Body",
  "errors": {
    "_errors": [
      {
        "code": "APPLICATION_COMMAND_TOO_LARGE",
        "message": "Command exceeds maximum size (8000)"
      }
    ]
  }
}
```

## Authentication

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

1. Using a bot token found on the Bot page within your app's settings. For more information on bots see [bots vs user accounts](/developers/topics/oauth2#bot-vs-user-accounts).
2. Using an OAuth2 bearer token gained through the [OAuth2 API](/developers/topics/oauth2).

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

**Example Bot Token Authorization Header**

```bash theme={"system"}
Authorization: Bot MTk4NjIyNDgzNDcxOTI1MjQ4.Cl2FMQ.ZnCjm1XVW7vRze4b7Cq4se7kKWs
```

**Example Bearer Token Authorization Header**

```bash theme={"system"}
Authorization: Bearer CZhtkLDpNYXgPH9Ml6shqh2OwykChw
```

## Encryption

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

## Snowflakes

Discord utilizes Twitter's [snowflake](https://github.com/twitter-archive/snowflake/tree/snowflake-2010) 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 [Gateway ETF/JSON](/developers/events/gateway#encoding-and-compression) 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)**

| Field               | Bits     | Number of bits | Description                                                                  | Retrieval                           |
| ------------------- | -------- | -------------- | ---------------------------------------------------------------------------- | ----------------------------------- |
| Timestamp           | 63 to 22 | 42 bits        | Milliseconds since Discord Epoch, the first second of 2015 or 1420070400000. | `(snowflake >> 22) + 1420070400000` |
| Internal worker ID  | 21 to 17 | 5 bits         |                                                                              | `(snowflake & 0x3E0000) >> 17`      |
| Internal process ID | 16 to 12 | 5 bits         |                                                                              | `(snowflake & 0x1F000) >> 12`       |
| Increment           | 11 to 0  | 12 bits        | For every ID that is generated on that process, this number is incremented   | `snowflake & 0xFFF`                 |

### Convert Snowflake to DateTime

<Snowflake />

### Snowflake IDs in Pagination

We typically use snowflake IDs in many of our API routes for pagination. The standardized pagination paradigm we utilize 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**

```bash theme={"system"}
(timestamp_ms - DISCORD_EPOCH) << 22
```

## ID Serialization

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

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

```bash theme={"system"}
// 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](https://www.loc.gov/standards/datetime/iso-tc154-wg5_n0038_iso_wd_8601-1_2016-02-16.pdf) for most Date/Times returned in our models. This format is referred to as type `ISO8601` within tables in this documentation.

## 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**

| Field                           | Type    |
| ------------------------------- | ------- |
| optional\_field?                | string  |
| nullable\_field                 | ?string |
| optional\_and\_nullable\_field? | ?string |

## Consistency

Discord operates at a scale where true consistency is impossible. Because of this, lots of operations in our API and in-between our services are [eventually consistent](https://en.wikipedia.org/wiki/Eventual_consistency). 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 must provide a valid [User Agent](https://www.rfc-editor.org/rfc/rfc9110.html#section-10.1.5) which specifies information about the client library and version in the following format:

**User Agent Example**

```bash theme={"system"}
User-Agent: DiscordBot ($url, $versionNumber)
```

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

<Note>
  Client requests that do not have a valid User Agent specified may be blocked and return a [Cloudflare error](https://support.cloudflare.com/hc/en-us/articles/360029779472-Troubleshooting-Cloudflare-1XXX-errors).
</Note>

### Content Type

Clients using the HTTP API must provide a valid `Content-Type` header, either `application/json`, `application/x-www-form-urlencoded`, or `multipart/form-data`, except where specified. Failing to do so will result in a `50035` "Invalid form body" error.

### Rate Limiting

The HTTP API implements a process for limiting and preventing excessive requests in accordance with [RFC 6585](https://tools.ietf.org/html/rfc6585#section-4). 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](/developers/topics/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.

### Array Query Strings

Certain endpoints in the API are documented to accept arrays for their query string parameters. Unless otherwise specified, Discord represents such cases using multiple instances of the same query string parameter. For example, `?id=123&id=456` for `["123", "456"]`.

## Gateway (WebSocket) API

Discord's Gateway API is used for maintaining persistent, stateful websocket connections between your client and our 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](https://tools.ietf.org/html/rfc6455). For information on opening Gateway connections, please see the [Gateway API](/developers/events/gateway#connections) section.

## 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:

<ManualAnchor id="message-formatting-formats" />

**Formats**

| Type                                | Structure                                | Example                               |
| ----------------------------------- | ---------------------------------------- | ------------------------------------- |
| User                                | `<@USER_ID>`                             | `<@80351110224678912>`                |
| User \*                             | `<@!USER_ID>`                            | `<@!80351110224678912>`               |
| Channel                             | `<#CHANNEL_ID>`                          | `<#103735883630395392>`               |
| Role                                | `<@&ROLE_ID>`                            | `<@&165511591545143296>`              |
| Slash command                       | `</NAME:COMMAND_ID>`                     | `</airhorn:816437322781949972>`       |
| Slash command with subcommand       | `</NAME SUBCOMMAND:ID>`                  | `</foo bar:123456789012345678>`       |
| Slash command with subcommand group | `</NAME SUBCOMMAND_GROUP SUBCOMMAND:ID>` | `</foo group bar:123456789012345678>` |
| Standard emoji                      | Unicode characters                       | 🪴                                    |
| Custom emoji                        | `<:NAME:ID>`                             | `<:mmLol:216154654256398347>`         |
| Animated custom emoji               | `<a:NAME:ID>`                            | `<a:b1nzy:392938283556143104>`        |
| Unix timestamp                      | `<t:TIMESTAMP>`                          | `<t:1618953630>`                      |
| Styled unix timestamp               | `<t:TIMESTAMP:STYLE>`                    | `<t:1618953630:d>`                    |
| Guild navigation                    | `<id:TYPE>`                              | See below                             |

Using the markdown for users or roles will mention the target(s), and notify them depending on the sender's permissions as well as the value of the `allowed_mentions` field when creating a message.
Standard emoji are currently rendered using [Twemoji](https://github.com/jdecked/twemoji) for Desktop and Android while iOS devices use Apple's native emoji set.

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

\* User mentions with an exclamation point are deprecated and should be handled like any other user mention.

<ManualAnchor id="message-formatting-timestamp-styles" />

**Timestamp Styles**

| Style | Example Output                   | Description             |
| ----- | -------------------------------- | ----------------------- |
| t     | 16:20                            | Short Time              |
| T     | 16:20:30                         | Medium Time             |
| d     | 20/04/2021                       | Short Date              |
| D     | April 20, 2021                   | Long Date               |
| f \*  | April 20, 2021 at 16:20          | Long Date, Short Time   |
| F     | Tuesday, April 20, 2021 at 16:20 | Full Date, Short Time   |
| s     | 20/04/2021, 16:20                | Short Date, Short Time  |
| S     | 20/04/2021, 16:20:30             | Short Date, Medium Time |
| R     | 4 years ago                      | Relative Time           |

\*default

**Guild Navigation Types**

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

| Full Syntax            | Linked Resource                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| `<id:customize>`       | Channel & Roles tab with [Onboarding prompts](/developers/resources/guild#guild-onboarding-object) |
| `<id:browse>`          | Browse Channels tab                                                                                |
| `<id:guide>`           | [Server Guide](https://support.discord.com/hc/en-us/articles/13497665141655) tab                   |
| `<id:linked-roles>`    | [Linked Roles](https://support.discord.com/hc/en-us/articles/10388356626711) tab                   |
| `<id:linked-roles:id>` | Specific linked role, opening the connection modal on click (the second `id` is the role id)       |

## Image Formatting

**Image Base URL**

```bash theme={"system"}
https://cdn.discordapp.com/
```

Discord uses ids and hashes to render images in the client. These hashes can be retrieved through various API requests, like [Get User](/developers/resources/user#get-user). Below are the formats, size limitations, and CDN endpoints for images in Discord. The returned format can be changed by changing the [extension name](/developers/reference#image-formatting-image-formats) at the end of the URL. The returned size can be changed by appending a querystring of `?size=desired_size` to the URL. Image size can be any power of two between 16 and 4096.

<Note>
  Animated images uploaded as WebP or AVIF do not convert cleanly to GIF. Apps should request animated images as WebP for maximum compatibility, as this works regardless of the original upload format.
</Note>

<ManualAnchor id="image-formatting-image-formats" />

**Image Formats**

| Name   | Extension   |
| ------ | ----------- |
| JPEG   | .jpg, .jpeg |
| PNG    | .png        |
| WebP   | .webp       |
| GIF    | .gif        |
| Lottie | .json       |

<ManualAnchor id="image-formatting-cdn-endpoints" />

**CDN Endpoints**

| Type                        | Path                                                                                                                                                                                                                                                                                                                                                                                   | Supports             |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| Custom Emoji                | emojis/[emoji\_id](/developers/resources/emoji#emoji-object).png \*\*\*\*\*                                                                                                                                                                                                                                                                                                            | PNG, JPEG, WebP, GIF |
| Guild Icon                  | icons/[guild\_id](/developers/resources/guild#guild-object)/[guild\_icon](/developers/resources/guild#guild-object).png \*                                                                                                                                                                                                                                                             | PNG, JPEG, WebP, GIF |
| Guild Splash                | splashes/[guild\_id](/developers/resources/guild#guild-object)/[guild\_splash](/developers/resources/guild#guild-object).png                                                                                                                                                                                                                                                           | PNG, JPEG, WebP      |
| Guild Discovery Splash      | discovery-splashes/[guild\_id](/developers/resources/guild#guild-object)/[guild\_discovery\_splash](/developers/resources/guild#guild-object).png                                                                                                                                                                                                                                      | PNG, JPEG, WebP      |
| Guild Banner                | banners/[guild\_id](/developers/resources/guild#guild-object)/[guild\_banner](/developers/resources/guild#guild-object).png \*                                                                                                                                                                                                                                                         | PNG, JPEG, WebP, GIF |
| User Banner                 | banners/[user\_id](/developers/resources/user#user-object)/[user\_banner](/developers/resources/user#user-object).png \*                                                                                                                                                                                                                                                               | PNG, JPEG, WebP, GIF |
| Default User Avatar         | embed/avatars/[index](/developers/resources/user#user-object).png \*\* \*\*\*                                                                                                                                                                                                                                                                                                          | PNG                  |
| User Avatar                 | avatars/[user\_id](/developers/resources/user#user-object)/[user\_avatar](/developers/resources/user#user-object).png \*                                                                                                                                                                                                                                                               | PNG, JPEG, WebP, GIF |
| Guild Member Avatar         | guilds/[guild\_id](/developers/resources/guild#guild-object)/users/[user\_id](/developers/resources/user#user-object)/avatars/[member\_avatar](/developers/resources/guild#guild-member-object).png \*                                                                                                                                                                                 | PNG, JPEG, WebP, GIF |
| Avatar Decoration           | avatar-decoration-presets/[avatar\_decoration\_data\_asset](/developers/resources/user#avatar-decoration-data-object).png                                                                                                                                                                                                                                                              | PNG                  |
| Application Icon            | app-icons/[application\_id](/developers/resources/application#application-object)/[icon](/developers/resources/application#application-object).png                                                                                                                                                                                                                                     | PNG, JPEG, WebP      |
| Application Cover           | app-icons/[application\_id](/developers/resources/application#application-object)/[cover\_image](/developers/resources/application#application-object).png                                                                                                                                                                                                                             | PNG, JPEG, WebP      |
| Application Asset           | app-assets/[application\_id](/developers/resources/application#application-object)/[asset\_id](/developers/events/gateway-events#activity-object-activity-assets).png                                                                                                                                                                                                                  | PNG, JPEG, WebP      |
| Achievement Icon            | app-assets/[application\_id](/developers/resources/application#application-object)/achievements/[achievement\_id](https://github.com/discord/discord-api-docs/blob/legacy-gamesdk/docs/game_sdk/Achievements.md#user-achievement-struct)/icons/[icon\_hash](https://github.com/discord/discord-api-docs/blob/legacy-gamesdk/docs/game_sdk/Achievements.md#user-achievement-struct).png | PNG, JPEG, WebP      |
| Store Page Asset            | app-assets/[application\_id](/developers/resources/application#application-object)/store/asset\_id                                                                                                                                                                                                                                                                                     | PNG, JPEG, WebP      |
| Sticker Pack Banner         | app-assets/710982414301790216/store/[sticker\_pack\_banner\_asset\_id](/developers/resources/sticker#sticker-pack-object).png                                                                                                                                                                                                                                                          | PNG, JPEG, WebP      |
| Team Icon                   | team-icons/[team\_id](/developers/topics/teams#data-models-team-object)/[team\_icon](/developers/topics/teams#data-models-team-object).png                                                                                                                                                                                                                                             | PNG, JPEG, WebP      |
| Sticker                     | stickers/[sticker\_id](/developers/resources/sticker#sticker-object).png \*\*\* \*\*\*\*                                                                                                                                                                                                                                                                                               | PNG, Lottie, GIF     |
| Role Icon                   | role-icons/[role\_id](/developers/topics/permissions#role-object)/[role\_icon](/developers/topics/permissions#role-object).png                                                                                                                                                                                                                                                         | PNG, JPEG, WebP      |
| Guild Scheduled Event Cover | guild-events/[scheduled\_event\_id](/developers/resources/guild-scheduled-event#guild-scheduled-event-object)/[scheduled\_event\_cover\_image](/developers/resources/guild-scheduled-event#guild-scheduled-event-object).png                                                                                                                                                           | PNG, JPEG, WebP      |
| Guild Member Banner         | guilds/[guild\_id](/developers/resources/guild#guild-object)/users/[user\_id](/developers/resources/user#user-object)/banners/[member\_banner](/developers/resources/guild#guild-member-object).png \*                                                                                                                                                                                 | PNG, JPEG, WebP, GIF |
| Guild Tag Badge             | guild-tag-badges/[guild\_id](/developers/resources/guild#guild-object)/[badge\_hash](/developers/resources/user#user-object-user-primary-guild).png                                                                                                                                                                                                                                    | PNG, JPEG, WebP      |

\* In the case of endpoints that support GIFs, the hash will begin with `a_` if it is available in an animated format (example: `a_1269e74af4df7417b13759eae50c83dc`). These images can be retrieved as animated WebP using the `.webp` file extension and `?animated=true` querystring parameter.

\*\* In the case of the Default User Avatar endpoint, the value for `index` depends on whether the user is [migrated to the new username system](/developers/change-log#unique-usernames-on-discord). For users on the new username system, `index` will be `(user_id >> 22) % 6`. For users on the legacy username system, `index` will be `discriminator % 5`.

\*\*\* In the case of the Default User Avatar and Sticker endpoints, the size of images returned is constant with the "size" querystring parameter being ignored.

\*\*\*\* In the case of the Sticker endpoint, the sticker will be available as PNG if its [`format_type`](/developers/resources/sticker#sticker-object) is `PNG` or `APNG`, GIF if its `format_type` is `GIF`, and as [Lottie](https://airbnb.io/lottie/#/) if its `format_type` is `LOTTIE`.

\*\*\*\*\* For Custom Emoji, we highly recommend requesting emojis as WebP for maximum performance and compatibility. Emojis can be uploaded as JPEG, PNG, GIF, WebP, and AVIF formats. WebP and AVIF formats must be requested as WebP since they don't convert well to other formats. The Discord client uses WebP for all emojis displayed in-app. See the [Emoji Resource](/developers/resources/emoji) page for more details.

<Info>
  Sticker GIFs do not use the CDN base URL, and can be accessed at `https://media.discordapp.net/stickers/<sticker_id>.gif`.
</Info>

## Image Data

Image data is a [Data URI scheme](https://en.wikipedia.org/wiki/Data_URI_scheme) that supports JPG, GIF, and PNG formats. An example Data URI format is:

```
data:image/jpeg;base64,BASE64_ENCODED_JPEG_IMAGE_DATA
```

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

### **Signed Attachment CDN URLs**

Attachments uploaded to Discord's CDN (like user and bot-uploaded images) have signed URLs with a preset expiry time. Discord automatically refreshes attachment CDN URLs that appear within the client, so when your app receives a payload with a signed URL (like when you [fetch a message](/developers/resources/message#get-channel-message)), it will be valid.

When passing CDN URLs into API fields, like [`url` in an embed image object](/developers/resources/message#embed-object-embed-image-structure) and [`avatar_url` for webhooks](/developers/resources/webhook#execute-webhook-jsonform-params), your app can pass the CDN URL without any parameters as the value and Discord will automatically render and refresh the URL.

The [standard CDN endpoints](/developers/reference#image-formatting-cdn-endpoints) listed above are not signed, so they will not expire.

###### Example Attachment CDN URL

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

###### Attachment CDN URL Parameters

| Parameter | Description                                                     |
| --------- | --------------------------------------------------------------- |
| ex        | Hex timestamp indicating when an attachment CDN URL will expire |
| is        | Hex timestamp indicating when the URL was issued                |
| hm        | Unique signature that remains valid until the URL's expiration  |

## Uploading Files

<Info>
  The file upload size limit applies to each file in a request. The default limit is `10 MiB` for all users, but may be higher for users depending on their [Nitro](https://support.discord.com/hc/en-us/articles/115000435108-What-are-Nitro-Nitro-Basic) status or by the server's [Boost Tier](https://support.discord.com/hc/en-us/articles/360028038352-Server-Boosting-FAQ-#h_419c3bd5-addd-4989-b7cf-c7957ef92583). The `attachment_size_limit` value provided [when working with interactions](/developers/interactions/receiving-and-responding#interaction-object-interaction-structure) is calculated as the maximum of these values.
</Info>

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](/developers/interactions/receiving-and-responding#interaction-response-object-interaction-callback-data-structure)).

Images can also be referenced in embeds using the `attachment://filename` URL. 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.

The `description` and `is_spoiler` fields of existing attachments can optionally be updated.

**Example Request Bodies (multipart/form-data)**

Note that these examples are small sections of an HTTP request to demonstrate behavior 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](https://tools.ietf.org/html/rfc7578#section-4).

This example demonstrates usage of the endpoint without `payload_json`.

```bash theme={"system"}
--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.

```bash theme={"system"}
--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://myfilename.png"
    },
    "image": {
      "url": "attachment://mygif.gif"
    }
  }],
  "message_reference": {
    "message_id": "233648473390448641"
  },
  "attachments": [{
      "id": 0,
      "description": "Image of a cute little cat",
      "filename": "myfilename.png"
  }, {
      "id": 1,
      "description": "Rickroll gif",
      "filename": "mygif.gif"
  }]
}
--boundary
Content-Disposition: form-data; name="files[0]"; filename="myfilename.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.

<Note>
  Only `.jpg`, `.jpeg`, `.png`, `.webp`, and `.gif` may be used at this time. Other file types are not supported.
</Note>

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

For example:

```bash theme={"system"}
{
  "embeds": [{
    "image": {
      "url": "attachment://screenshot.png"
    }
  }]
}
```

## Locales

| Locale | Language Name         | Native Name         |
| ------ | --------------------- | ------------------- |
| id     | Indonesian            | Bahasa Indonesia    |
| da     | Danish                | Dansk               |
| de     | German                | Deutsch             |
| en-GB  | English, UK           | English, UK         |
| en-US  | English, US           | English, US         |
| es-ES  | Spanish               | Español             |
| es-419 | Spanish, LATAM        | Español, LATAM      |
| fr     | French                | Français            |
| hr     | Croatian              | Hrvatski            |
| it     | Italian               | Italiano            |
| lt     | Lithuanian            | Lietuviškai         |
| hu     | Hungarian             | Magyar              |
| nl     | Dutch                 | Nederlands          |
| no     | Norwegian             | Norsk               |
| pl     | Polish                | Polski              |
| pt-BR  | Portuguese, Brazilian | Português do Brasil |
| ro     | Romanian, Romania     | Română              |
| fi     | Finnish               | Suomi               |
| sv-SE  | Swedish               | Svenska             |
| vi     | Vietnamese            | Tiếng Việt          |
| tr     | Turkish               | Türkçe              |
| cs     | Czech                 | Čeština             |
| el     | Greek                 | Ελληνικά            |
| bg     | Bulgarian             | български           |
| ru     | Russian               | Pусский             |
| uk     | Ukrainian             | Українська          |
| hi     | Hindi                 | हिन्दी              |
| th     | Thai                  | ไทย                 |
| zh-CN  | Chinese, China        | 中文                  |
| ja     | Japanese              | 日本語                 |
| zh-TW  | Chinese, Taiwan       | 繁體中文                |
| ko     | Korean                | 한국어                 |