Guild stickers

A sticker is an image a guild stores for its members to send with a message. It belongs to exactly one guild. Its snowflake is unique across every guild. Get sticker metadata resolves a sticker without membership of its guild.

Every route names a guild in its path. A guild that has UNAVAILABLE_FOR_EVERYONE rejects the request with 403 MISSING_ACCESS before the operation runs. UNAVAILABLE_FOR_EVERYONE_BUT_STAFF does the same for an account without the instance staff flag. On Clone guild sticker the gate covers the target guild and never the source guild.

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

A guild that does not exist returns 404 UNKNOWN_GUILD. A caller who is not a current member of an existing guild returns 403 MISSING_PERMISSIONS, so guild existence is distinguishable from guild membership. Modify guild sticker returns 404 UNKNOWN_STICKER for a guild that does not exist.

There is no single-sticker read scoped to a guild. List guild stickers returns the whole collection in one response.

Guild sticker object

A guild sticker object describes one sticker. Only its name, description and tags can change. Replacing the image requires creating a new sticker.

Structure

Field	Type	Description
id	snowflake	The ID of the sticker
name	string	The name of the sticker (2-30 characters)
description1	string	The sticker description, or an empty string when it has none
tags	array[string]	Sticker tags
animated2	boolean	Whether the stored image is animated
user?3	partial user object	The account that uploaded the sticker

¹ Never null on the wire. A sticker with no description has an empty string

² Detected from the submitted image at creation, and copied unchanged by Clone guild sticker

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

A sticker is always a guild sticker, and animated alone describes its format. The object has no sticker type, format type, or availability field.

Example

{
  "id": "1501314428688998183",
  "name": "shipit",
  "description": "Ship it",
  "tags": ["ship", "deploy"],
  "animated": false
}

Sticker tags

Tags are an array of strings. A create or modify request accepts at most 10 entries. FiveCord trims each entry. The 1 to 30 character bound applies to the trimmed value. Entries are stored and returned in the submitted order.

The array is optional on every request that accepts it and defaults to an empty array, so omitting it on Modify guild sticker clears the stored tags.

Sticker create object

The item shape shared by Create guild sticker and each entry of Bulk create guild stickers.

Structure

Field	Type	Description
name1	string	The name of the sticker (2-30 characters)
description?2	?string	The sticker description (1-500 characters), or null for none
tags?	array[string]	Sticker tags, defaulting to an empty array
image3	base64 string	The image data, with at most 524288 decoded bytes

¹ The value is trimmed before the bound applies, as it is for description and each tag

² An omitted value and null are both stored as null and returned as an empty string

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

The remaining encoded part is bounded to 699052 characters, which encodes a full 524288 byte image, and 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.

Decoded bytes are at most the operator-configured sticker_max_size limit key value, resolved against the guild’s complete feature set and defaulting to 524288. A larger image is rejected on the image path with IMAGE_SIZE_EXCEEDS_LIMIT, whose message names the resolved ceiling. An image over 524289 bytes exceeds the 699052 character bound and returns BASE64_LENGTH_INVALID, so a configured value above 524289 never applies.

Accepted upload formats are PNG, JPEG, APNG, GIF, WebP, AVIF, and SVG. FiveCord takes the format from the decoded image. An animated AVIF is rejected. FiveCord detects animation state from the image, so this object has no animation field.

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

Example

{
  "name": "shipit",
  "description": "Ship it",
  "tags": ["ship", "deploy"],
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAAAAAA6fptVAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg=="
}

Sticker bulk create response object

The outcome of one Bulk create guild stickers call, split into the items that were created and the items that were rejected.

Structure

Field	Type	Description
success	array[guild sticker object]	The stickers that were created
failed	array[sticker creation failure object]	The items rejected after top-level request validation

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

Example

{
  "success": [],
  "failed": [{"name": "shipit", "error": "The image is too large."}]
}

Sticker creation failure object

One rejected item from a bulk create call, named and explained in display text.

Structure

Field	Type	Description
name1	string	The requested sticker 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

There is no machine-readable code, so a client that needs to branch on the reason submits that item again through Create guild sticker, which returns an error code.

List guild stickers

GET/v1/guilds/{guild_id}/stickersBot

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

One response has the complete collection. The operation is not paginated. A sticker whose uploader cannot be resolved is omitted, so the array can be shorter than the number of stored stickers.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response

Status	Body	Condition
200	array[guild sticker object]	Stickers 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:sticker:list::guild_id bucket.

Create guild sticker

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

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

The slot limit is the operator-configured max_guild_stickers value resolved against the guild’s complete feature set, defaulting to 500. A guild with UNLIMITED_STICKERS 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 sticker create object.

Response

Status	Body	Condition
200	guild sticker object	Sticker was created
4001	error response	Guild is at its sticker slot limit, or the image is invalid
4032	error response	Guild is unavailable, the caller is not a member or lacks CREATE_EXPRESSIONS, or the submitted text or image is blocked
404	error response	Guild does not exist and the request returns UNKNOWN_GUILD

¹ The error code is MAX_STICKERS for the slot limit, with the resolved limit in its message variables. An image failure is INVALID_FORM_BODY 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 MISSING_ACCESS for an unavailable guild, MISSING_PERMISSIONS for a membership or permission failure, and CONTENT_BLOCKED when the name, description, or a tag matches a blocklist or the decoded image matches a banned file hash

Side effects

Creating a sticker consumes one guild sticker slot, emits Guild Stickers Update with the complete collection and records a STICKER_CREATE audit entry with the supplied reason.

Rate limit

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

Bulk create guild stickers

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

Attempts to create between 1 and 50 stickers in one request and returns a sticker bulk create response object. Emits one Guild Stickers Update Gateway event for the whole batch.

The caller needs membership of the guild and CREATE_EXPRESSIONS. FiveCord processes the items strictly in the submitted order and treats each one independently. An item fails when no guild sticker slot remains. A later item can still succeed after an earlier item failed for another reason.

A 200 does not mean every item succeeded

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 stickers 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
stickers	array[sticker create object]	The items to create, in the order they are processed (1-50)

Response

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

¹ An oversized encoded image, an out-of-range name, or a tag outside its bound rejects the whole request before any item is created

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

A decoded image that is oversized, undecodable, in an unaccepted format, or matching a banned file hash fails one item.

Blocked text can reject the whole batch

A blocked name, description or tag of at least 3 characters rejects the whole request. A shorter blocked value fails only that item.

Side effects

Each successful item consumes one guild sticker slot and records a STICKER_CREATE audit entry with the supplied reason.

FiveCord emits one Guild Stickers Update after the batch when at least one item succeeded, with the guild’s complete sticker collection. A batch in which no item succeeded emits nothing.

Rate limit

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

Clone guild sticker

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

Copies an existing sticker into the target guild and returns the new guild sticker object without user. Emits a Guild Stickers Update Gateway event in the target guild.

The caller needs membership of the target guild and CREATE_EXPRESSIONS there. Membership of the source guild is not required. The source guild must have CLONE_STICKER_ENABLED, which a guild holds only after it opts in.

The name, description, tags, animation state and image are copied unchanged.

Get sticker metadata reports whether a source permits cloning without attempting the operation.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the target guild

JSON body

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

Response

Status	Body	Condition
200	guild sticker object	Sticker was cloned
4001	error response	Target guild is at its sticker 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 sticker or target guild does not exist

¹ The error code is MAX_STICKERS

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

³ The error code is UNKNOWN_STICKER for the source sticker 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 sticker slot and names the caller as uploader. It emits Guild Stickers Update in the target guild and records a STICKER_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:sticker:clone::guild_id bucket.

Modify guild sticker

PATCH/v1/guilds/{guild_id}/stickers/{sticker_id}BotAudit reason

Replaces sticker metadata and returns the guild sticker object without user. Emits a Guild Stickers Update Gateway event.

Limitations

• The uploader can modify their own sticker with CREATE_EXPRESSIONS, and any other caller requires MANAGE_EXPRESSIONS.
• Neither permission is subject to the guild MFA level.
• The stored image cannot be replaced, so an image change requires creating a new sticker.

A sticker that does not belong to the guild in the path returns 404 UNKNOWN_STICKER.

Every request writes description and tags

Only name is required. Omitting description clears the stored description and omitting tags clears the stored tags. A client changing one field submits the current value of the other two alongside it.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild
sticker_id	snowflake	The ID of the sticker

JSON body

Field	Type	Description
name	string	The name of the sticker (2-30 characters)
description?1	?string	The sticker description (1-500 characters), or null to clear it
tags?2	array[string]	Sticker tags, defaulting to an empty array

¹ An omitted value and null are both stored as null and returned as an empty string

² An omitted array is written as an empty array

Response

Status	Body	Condition
200	guild sticker object	Metadata was processed
4031	error response	Guild is unavailable, the caller is neither the uploader with CREATE_EXPRESSIONS nor a member holding MANAGE_EXPRESSIONS, or the submitted text is blocked
404	error response	Sticker does not exist in that guild and the request returns UNKNOWN_STICKER

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

A non-member who names an existing sticker receives MISSING_PERMISSIONS.

Side effects

The operation writes the supplied metadata, emits Guild Stickers Update with the guild’s complete sticker collection, and then records a STICKER_UPDATE audit entry. Submitted values that match the stored ones still emit the Dispatch and record no audit entry.

Rate limit

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

Delete guild sticker

DELETE/v1/guilds/{guild_id}/stickers/{sticker_id}BotAudit reason

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

Limitations

• The uploader can delete their own sticker with CREATE_EXPRESSIONS, and any other caller requires MANAGE_EXPRESSIONS.
• Setting purge needs the guild to have EXPRESSION_PURGE_ALLOWED.

Purging the stored image cannot be undone

Without purge, the sticker 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 sticker does not affect an existing clone in another guild.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild
sticker_id	snowflake	The ID of the sticker

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	Sticker 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 sticker 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_STICKER for the sticker

Side effects

The operation removes the sticker from the guild, returns its slot, emits Guild Stickers Update with the guild’s remaining sticker collection, and then writes a STICKER_DELETE audit entry.

With purge, the image can remain available briefly after the 204. Existing messages that reference the sticker are unchanged.

Rate limit

10 requests per 30 seconds for each authenticated user and guild ID, on the guild:sticker:delete::guild_id bucket. The route charges a second allowance of 300 requests per day for each authenticated user and guild ID, on the guild:sticker:delete:daily::guild_id bucket.