Admin badges

A custom badge is an image that instance admins make and give out. A user badge shows on the profile of each account it’s given to, after the built-in badges. A guild badge shows next to the guild name, after its verified, partnered or discoverable badge, and instance discovery lists every guild badge for clients.

You can make up to 10 badges of each type, and an account or guild can have up to 10. Give badges with Update user badges and the badge_ids field of Update guild. Deleting a badge takes it off everyone who had it.

Admin custom badge object

Structure

Field	Type	Description
id	snowflake	The ID of the badge
type	string	`user` or `guild`
name	string	The name of the badge (1-64 characters)
description	?string	The tooltip text under the name (1-256 characters), or null
asset_url	string	The badge image as WebP from the media proxy
href	?string	The `https` URL a click opens, or null

Example

{
  "id": "1489002177550843904",
  "type": "user",
  "name": "Translator",
  "description": "Helps translate Fluxer",
  "asset_url": "https://media.example.com/custom-badges/1489002177550843904/3f2a9c1d.webp",
  "href": null
}

List badges

GET/v1/admin/badges

Audit reason

Returns every custom badge in display order, which is the order they were made in. You need badge:list.

Response body

Field	Type	Description
badges	array[Admin custom badge object]	The badges of both types

Response

Status	Body	Condition
200	response body	The badges were returned

The rate limit is 200 requests per minute, on the admin:lookup bucket.

Create badge

POST/v1/admin/badges

Audit reason

Uploads the image to the media proxy, makes the badge and returns it. You need badge:create.

JSON body

Field	Type	Description
type	string	`user` or `guild`
name	string	The name of the badge (1-64 characters)
description?	?string	The tooltip text (1-256 characters)
href?	?string	The `https` URL a click opens
image¹	string	The image as a base64 data URI (up to 16000000 characters)

¹ Up to the avatar_max_size limit, 10 MiB by default, as PNG, JPEG, WebP, GIF, APNG, still AVIF, HEIC, HEIF, JXL or SVG, and at least 128 by 128 pixels. Clients always get a WebP version

Response

Status	Body	Condition
200	Admin custom badge object	The badge was made
400	error response	`MAX_BADGES` when the type already has 10 badges, or `INVALID_FORM_BODY` for a bad field
400	error response	`IMAGE_SIZE_EXCEEDS_LIMIT`, `INVALID_IMAGE_FORMAT` or `FAILED_TO_UPLOAD_IMAGE` for a bad image

The rate limit is 100 requests per minute, on the admin:user:modify bucket.

Update badge

PATCH/v1/admin/badges/{badge_id}

Audit reason

Replaces the name, description and link of a badge, and its image when you send one, and returns the badge. The type can’t change. You need badge:update.

JSON body

Field	Type	Description
name	string	The name of the badge (1-64 characters)
description	?string	The tooltip text under the name (1-256 characters), or null
href	?string	The `https` URL a click opens, or null
image?¹	string	A new image as a base64 data URI. Leave it out to keep the current one

¹ The same formats and limits as Create badge

Response

Status	Body	Condition
200	Admin custom badge object	The badge was updated
400	error response	`INVALID_FORM_BODY` for a bad field
400	error response	`IMAGE_SIZE_EXCEEDS_LIMIT`, `INVALID_IMAGE_FORMAT` or `FAILED_TO_UPLOAD_IMAGE` for a bad image
404	error response	`UNKNOWN_BADGE` when the badge doesn’t exist

The rate limit is 100 requests per minute, on the admin:user:modify bucket.

Delete badge

DELETE/v1/admin/badges/{badge_id}

Audit reason

Deletes a badge and its image and returns 204. Accounts and guilds that had it stop showing it. You need badge:delete.

Response

Status	Body	Condition
204	none	The badge was deleted
404	error response	`UNKNOWN_BADGE` when the badge doesn’t exist

The rate limit is 100 requests per minute, on the admin:user:modify bucket.