Guild emojis

An emoji is a custom image that one guild owns. Members use it in messages and reactions. Its ID is a snowflake that is unique across every guild. List guild emojis is the only guild-scoped read, and Get emoji metadata resolves a single emoji without membership of its guild.

Every route names a guild in its path. When that guild has UNAVAILABLE_FOR_EVERYONE, FiveCord rejects the request with 403 MISSING_ACCESS before the operation runs. FiveCord does the same for a guild with UNAVAILABLE_FOR_EVERYONE_BUT_STAFF when the account has no instance staff flag.

A guild that does not exist returns 404 UNKNOWN_GUILD. FiveCord returns 403 MISSING_PERMISSIONS to a caller who is not a current member of an existing guild, so guild existence is distinguishable from guild membership. On Modify guild emoji a non-member receives the same 403 MISSING_PERMISSIONS, and a guild that does not exist returns 404 UNKNOWN_EMOJI.

Names and uploaded images must pass the instance’s content policy. Blocked content returns 403 CONTENT_BLOCKED.

Guild emoji object

Only name can be changed after creation. The stored image is written once at creation and is never replaced.

Structure

Field	Type	Description
id	snowflake	The ID of the emoji
name	string	The name of the emoji (2-32 characters)
animated1	boolean	Whether the stored image is animated
user?2	partial user object	The account that uploaded the emoji

¹ Detected from the submitted image at creation, and copied unchanged by Clone guild emoji

² Present only on List guild emojis, where it is set for every caller and requires no permission

Example

{
  "id": "1501314428688998182",
  "name": "party_parrot",
  "animated": true
}

Emoji create object

The image and name submitted for one new emoji.

Structure

Field	Type	Description
name1	string	The name of the emoji (2-32 characters, ASCII letters, digits, and underscore)
image2 3	base64 string	The image to store (at most the resolved emoji_max_size limit in decoded bytes, 524288 by default)

¹ The value is trimmed, and both bounds apply to the trimmed value

² A data URL prefix is accepted and everything up to the first comma is removed before any bound applies

³ The decoded ceiling is the resolved emoji_max_size limit key in guild scope, 524288 bytes by default

The remaining encoded part is bounded to 699052 characters, the base64 expansion of the 524288 byte default. A longer value returns the validation code BASE64_LENGTH_INVALID at the image path. A value that is not canonical base64 with correct padding returns INVALID_BASE64_FORMAT. An image over the resolved ceiling returns IMAGE_SIZE_EXCEEDS_LIMIT at the same path, and maxSize is the ceiling that applied.

The 699052 character bound does not move with the limit key, so a resolved ceiling above 524288 bytes admits no more than 524289 decoded bytes.

Accepted upload formats are PNG, JPEG, WebP, GIF, APNG, AVIF, HEIC, HEIF, JXL, and SVG. FiveCord takes the format and the animation state from the decoded image. An animated AVIF is rejected.

Pixel dimensions are not enforced. An accepted image is stored at its original dimensions and the Media Proxy image asset contract selects the delivered size.

Example

{
  "name": "party_parrot",
  "image": "data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAI="
}

Emoji bulk create response object

The outcome of one bulk creation, holding one entry for every submitted item.

Structure

Field	Type	Description
success	array[guild emoji object]	The emojis this request created
failed	array[expression creation failure object]	The items rejected after top-level request validation

Both arrays are present on every success response, and either can be empty. An item appears in exactly one of them, so the combined length equals the submitted item count.

Example

{
  "success": [{"id": "1501314428688998182", "name": "party_parrot", "animated": true}],
  "failed": [{"name": "too_big", "error": "The image is too large."}]
}

Expression creation failure object

One item a bulk creation rejected, identified only by the name the caller submitted.

Structure

Field	Type	Description
name1	string	The name echoed from the submitted item
error2	string	The failure message rendered for the item

¹ The object has no index, so two submitted items sharing a name cannot be told apart

² Rendered in the locale of the authenticated account, so its value changes with the caller’s locale

The failure contains display text, not a machine-readable code. Retry an item through Create guild emoji if a structured error is needed.

List guild emojis

GET/v1/guilds/{guild_id}/emojisBot

Returns every guild emoji object of the guild, each with user. Requires membership of the guild and no permission.

FiveCord returns the complete collection in one response, and the operation has no pagination parameters. An emoji whose uploader cannot be resolved is omitted, so the array can be shorter than the number of stored emojis.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response

Status	Body	Condition
200	array[guild emoji object]	Emojis were returned
4031	error response	Guild is unavailable, or the caller is not a member
404	error response	Guild does not exist and the request returns UNKNOWN_GUILD

¹ The error code is MISSING_ACCESS for an unavailable guild and MISSING_PERMISSIONS for a non-member

Rate limit

60 requests per 10 seconds for each authenticated user and guild ID, on the guild:emojis:list::guild_id bucket.

Create guild emoji

POST/v1/guilds/{guild_id}/emojisBotAudit reason

Creates one emoji from submitted image data and returns its guild emoji object without user. Requires membership of the guild and CREATE_EXPRESSIONS. Emits a Guild Emojis Update Gateway event.

The slot limit is the operator-configured max_guild_emojis value resolved against the guild’s complete feature set, defaulting to 500. A guild with UNLIMITED_EMOJI bypasses that configuration and receives a fixed ceiling of 999999.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

JSON body

The body is one emoji create object.

Response

Status	Body	Condition
200	guild emoji object	Emoji was created
4001	error response	Guild is at its emoji slot limit, or the image is undecodable, oversized, or in an unaccepted format
4032	error response	Name is blocked, the guild is unavailable, the caller is not a member or lacks CREATE_EXPRESSIONS, or the image hash is banned
404	error response	Guild does not exist and the request returns UNKNOWN_GUILD

¹ The error code is MAX_EMOJIS for the slot limit, with the resolved limit in its message variables, and INVALID_FORM_BODY for an image failure, with BASE64_LENGTH_INVALID for an oversized encoding, IMAGE_SIZE_EXCEEDS_LIMIT for decoded bytes over the resolved ceiling, or INVALID_IMAGE_FORMAT for an undecodable or unaccepted image at the image path

² The error code is CONTENT_BLOCKED for a blocked name and for a banned image hash, MISSING_ACCESS for an unavailable guild, and MISSING_PERMISSIONS for a membership or permission failure

Side effects

Creating an emoji consumes one guild emoji slot, emits Guild Emojis Update with the complete collection and records an EMOJI_CREATE audit entry with the supplied reason.

Rate limit

10 requests per 30 seconds for each authenticated user and guild ID, on the guild:emoji:create::guild_id bucket.

Bulk create guild emojis

POST/v1/guilds/{guild_id}/emojis/bulkBotAudit reason

Attempts to create between 1 and 50 emojis in one request and returns an emoji bulk create response object. Requires membership of the guild and CREATE_EXPRESSIONS. Emits one Guild Emojis Update Gateway event for the whole batch.

FiveCord processes the items strictly in the submitted order and treats each one independently. Once the guild is full, every remaining item fails with the limit. A later item can still succeed after an earlier item failed for any other reason.

An undecodable image, an unaccepted format, and a banned hash each fail one item and leave the rest of the batch to run.

200 does not mean every item was created

The operation returns 200 whenever the top-level request was valid, including when every item failed. Read success and failed for the per-item outcome. The emojis in success are durable and are not rolled back when a later item fails.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

JSON body

Field	Type	Description
emojis	array[emoji create object]	The items to create, attempted in the order supplied (1-50)

Response

Status	Body	Condition
200	emoji bulk create response object	Every validated item was attempted
4001	error response	Top-level body, item count, item shape, item name, or encoded image bound is invalid
4032	error response	An item name is blocked, the guild is unavailable, or the caller is not a member or lacks CREATE_EXPRESSIONS
404	error response	Guild does not exist and the request returns UNKNOWN_GUILD

¹ Boundary validation rejects the whole request, so an oversized encoded image in one item fails before any item is created

² The error code is CONTENT_BLOCKED for a blocked item name, MISSING_ACCESS for an unavailable guild, and MISSING_PERMISSIONS for a membership or permission failure

One blocked name rejects the whole request without creating any emojis.

Side effects

Each successful item consumes one guild emoji slot and records an EMOJI_CREATE audit entry with the supplied reason. If any item succeeds, one Guild Emojis Update contains the guild’s complete emoji collection.

Rate limit

6 requests per minute for each authenticated user and guild ID, on the guild:emoji:bulk_create::guild_id bucket.

Clone guild emoji

POST/v1/guilds/{guild_id}/emojis/cloneBotAudit reason

Copies an existing emoji into the target guild and returns the new guild emoji object without user. Requires membership of the target guild and CREATE_EXPRESSIONS there. Emits a Guild Emojis Update Gateway event in the target guild.

The name, animation state and image are copied unchanged. Membership of the source guild is not required. The source guild must have CLONE_EMOJI_ENABLED.

Get emoji metadata reports whether a source permits cloning.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the target guild

JSON body

Field	Type	Description
source_emoji_id	snowflake	The ID of the emoji to copy, which can belong to any guild

Response

Status	Body	Condition
200	guild emoji object	Emoji was cloned
4001	error response	Target guild is at its emoji slot limit
4032	error response	Source guild is missing or does not permit cloning, the target guild is unavailable, or the caller is not a member of the target guild or lacks CREATE_EXPRESSIONS there
4043	error response	Source emoji or target guild does not exist

¹ The error code is MAX_EMOJIS

² The error code is MISSING_ACCESS when the source guild is missing or lacks CLONE_EMOJI_ENABLED and when the target guild is unavailable, and MISSING_PERMISSIONS for a target membership or permission failure

³ The error code is UNKNOWN_EMOJI for the source emoji and UNKNOWN_GUILD for the target guild

A source guild that no longer exists returns 403 MISSING_ACCESS, so a caller cannot tell it apart from a source guild that does not permit cloning.

Side effects

The copy consumes one target guild emoji slot and names the caller as uploader. It emits Guild Emojis Update in the target guild and records an EMOJI_CREATE audit entry. The source is unchanged.

Rate limit

10 requests per 30 seconds for each authenticated user and target guild ID, on the guild:emoji:clone::guild_id bucket.

Modify guild emoji

PATCH/v1/guilds/{guild_id}/emojis/{emoji_id}BotAudit reason

Renames an emoji and returns its guild emoji object without user. Emits a Guild Emojis Update Gateway event.

Limitations

• The uploader can rename their own emoji with CREATE_EXPRESSIONS.
• Any other caller requires MANAGE_EXPRESSIONS.

Neither permission is subject to the guild MFA level.

An emoji that does not belong to the guild in the path returns 404 UNKNOWN_EMOJI.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild
emoji_id	snowflake	The ID of the emoji

JSON body

Field	Type	Description
name	string	The new name of the emoji (2-32 characters, ASCII letters, digits, and underscore)

Response

Status	Body	Condition
200	guild emoji object	Name was set, including a name equal to the current one
4001	error response	Path parameter or name is invalid
4032	error response	Name is blocked, the guild is unavailable, or the caller is neither the uploader with CREATE_EXPRESSIONS nor a member holding MANAGE_EXPRESSIONS
404	error response	Emoji does not exist in that guild and the request returns UNKNOWN_EMOJI

¹ The error code is INVALID_FORM_BODY with INVALID_SNOWFLAKE_FORMAT or SNOWFLAKE_OUT_OF_RANGE for a path parameter, STRING_LENGTH_INVALID for a name outside 2 to 32 characters after normalisation, and INVALID_FORMAT for a disallowed character

² The error code is CONTENT_BLOCKED for a blocked name, MISSING_ACCESS for an unavailable guild, and MISSING_PERMISSIONS for a permission failure

Side effects

The operation sets the requested name, emits Guild Emojis Update with the guild’s complete emoji collection, and then writes an EMOJI_UPDATE audit entry. A submitted name that equals the current name still emits the Dispatch and records no audit entry.

Rate limit

20 requests per 10 seconds for each authenticated user and guild ID, on the guild:emoji:update::guild_id bucket.

Delete guild emoji

DELETE/v1/guilds/{guild_id}/emojis/{emoji_id}BotAudit reason

Deletes the emoji record and returns 204 with an empty body. Emits a Guild Emojis Update Gateway event.

Limitations

• The uploader can delete their own emoji with CREATE_EXPRESSIONS.
• Any other caller requires MANAGE_EXPRESSIONS.

Neither permission is subject to the guild MFA level.

A purge cannot be undone through the API

Without purge, the emoji leaves the guild but its image remains available through the Media Proxy. With purge, the image is scheduled for permanent deletion.

A clone outlives a purge of its source

A later purge of the source emoji does not affect an existing clone in another guild.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild
emoji_id	snowflake	The ID of the emoji

Query parameters

Field	Type	Description
purge?1	boolean	Whether to permanently delete the stored image (default false)

¹ Read as true only when it is exactly true, True, or 1 after trimming. Every other value, including TRUE and yes, reads as false

Response

Status	Body	Condition
204	empty	Emoji record was deleted
4031	error response	Guild is unavailable or cannot purge expression assets, or the caller is neither the uploader with CREATE_EXPRESSIONS nor a member holding MANAGE_EXPRESSIONS
4042	error response	Guild or emoji does not exist

¹ The error code is MISSING_ACCESS for an unavailable guild and when purge is true and the guild lacks EXPRESSION_PURGE_ALLOWED, and MISSING_PERMISSIONS for a membership or permission failure

² The error code is UNKNOWN_GUILD for the guild and UNKNOWN_EMOJI for the emoji

Side effects

Deletion frees one guild emoji slot, emits Guild Emojis Update with the remaining collection and records an EMOJI_DELETE audit entry. Existing messages that reference the emoji are unchanged.

Rate limit

10 requests per 30 seconds for each authenticated user and guild ID, on the guild:emoji:delete::guild_id bucket. The route also draws on the guild:emoji:delete:daily::guild_id bucket of 300 requests per day for each authenticated user and guild ID.