Badges
A badge is displayed next to a user’s name in their profile, or next to the guild icon in its profile. Some built-in badges are automatically defined, namely Staff and Premium (for users) and Verified, Partnered and Discoverable (for guilds). The icons for these internal badges can be overridden, but no other property can be edited.
Update user badges and Update guild badges assign badges. List badges provides a list of user or guild badges.
List badges
Section titled “List badges”GET/v1/admin/badgesReturns the badges object. Requires badge:list.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | badges object | The badges were returned |
Side effects
Section titled “Side effects”The operation records one read Admin audit entry with action list_badges and the metadata key result_count.
Rate limit
Section titled “Rate limit”200 requests per minute for each authenticated user, on the admin:lookup bucket.
Create badge
Section titled “Create badge”POST/v1/admin/badgesCreates a badge and returns it. Requires badge:create.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| type | string | user or guild |
| name | string | The name of the badge (1-64 characters) |
| tooltip | string | The text shown when hovering over the badge image (1-256 characters) |
| icon | string | The SVG markup of the icon |
| url? | ?string | The absolute HTTP URL opened when the badge is clicked, if any |
| position? | integer | The order in which the badge appears in a profile |
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| badge | badge object | The created badge |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The badge was created |
| 400 | error response | INVALID_FORM_BODY or MAX_BADGES |
Side effects
Section titled “Side effects”Badges Update is emitted with the new badge. The operation records one Admin audit entry with action create_badge, target type badge, the badge ID as the target, and the metadata keys type and name.
Rate limit
Section titled “Rate limit”200 requests per minute for each authenticated user, on the admin:general bucket.
Update badge
Section titled “Update badge”PATCH/v1/admin/badges/{badge_id}Applies a partial update to a badge and returns it. Requires badge:update.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| badge_id | snowflake | The ID of the badge |
JSON body
Section titled “JSON body”Every field is optional and an omitted field is left unchanged.
| Field | Type | Description |
|---|---|---|
| name? | string | The name of the badge (1-64 characters) |
| tooltip? | string | The text shown when hovering over the badge (1-256 characters) |
| icon? | string | The replacement SVG markup |
| url? | string | The absolute HTTP URL opened when the badge is clicked, or null for none |
| position? | integer | The order in which the badge appears in a profile |
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| badge | badge object | The updated badge |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The badge was updated |
| 400 | error response | INVALID_FORM_BODY, because a field or the icon failed validation |
| 404 | error response | UNKNOWN_BADGE, because the badge does not exist |
Side effects
Section titled “Side effects”Badges Update is emitted with the updated badge. The operation records one Admin audit entry with action update_badge, target type badge, the badge ID as the target, and the metadata key fields.
Rate limit
Section titled “Rate limit”200 requests per minute for each authenticated user, on the admin:general bucket.
Delete badge
Section titled “Delete badge”DELETE/v1/admin/badges/{badge_id}Deletes a badge. Requires badge:delete. Accounts and guilds keep the badge ID, and clients stop showing it because no definition resolves it.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| badge_id | snowflake | The ID of the badge |
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| success | boolean | Always true |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The badge was deleted |
| 404 | error response | UNKNOWN_BADGE, because the badge does not exist |
Side effects
Section titled “Side effects”Badges Update is emitted with the deleted badge ID. The operation records one Admin audit entry with action delete_badge, target type badge, the badge ID as the target, and the metadata keys type and name.
Rate limit
Section titled “Rate limit”200 requests per minute for each authenticated user, on the admin:general bucket.
Update built-in badge icon
Section titled “Update built-in badge icon”PUT/v1/admin/badges/builtin/{badge}Overrides the icon of a built-in badge, or restores its default icon, and returns the built-in badge icons object. Requires badge:update.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| badge | string | staff, premium, verified, partnered, or discoverable |
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| icon? | string | The SVG markup of the icon, or null to restore the default icon |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | built-in badge icons object | The icon was updated |
| 400 | error response | INVALID_FORM_BODY, because the icon failed validation |
Side effects
Section titled “Side effects”Badges Update is emitted with the changed icon. The operation records one Admin audit entry with action update_builtin_badge_icon, target type badge, and the metadata keys badge and reset.
Rate limit
Section titled “Rate limit”200 requests per minute for each authenticated user, on the admin:general bucket.