Badges

The badge inventory lists every badge the caller owns, hidden ones included. Hiding a badge only removes it from what other readers see, and the caller keeps it.

Every route here requires a user session. A bot or OAuth2 bearer credential is refused with 403 ACCESS_DENIED.

A badge comes from one of two sources. A built-in badge follows from the account itself: an account flag or its premium state. A catalog badge is one of the badges an Admin gives to the account.

Built-in badge object

One built-in badge the caller owns.

Structure

Field	Type	Description
source1	string	flag or premium
key2	string	Which built-in badge this is
visible	boolean	Whether other readers see the badge

¹ flag for staff, partner and bug_hunter, and premium for the other keys

² One of the keys in Built-in badge keys

Built-in badge keys

Key	Owned while
staff	The account has the STAFF user flag
partner	The account has the PARTNER user flag
bug_hunter	The account has the BUG_HUNTER user flag
premium	The account has premium
premium_package	The account has a lasting package badge and no lifetime premium
premium_sequence	The account has lifetime premium with a sequence number

Hiding any key except premium_sequence removes the matching flags from the account’s public flags: PREMIUM_BADGE for premium, and every package badge flag for premium_package. Hiding premium_sequence removes the lifetime sequence from the public profile.

Catalog badge object

One catalog badge the caller owns.

Structure

Field	Type	Description
source	string	Always catalog
badge_id	snowflake	The ID of the badge
visible	boolean	Whether the badge shows on the caller’s profile
icon	string	The hash of the badge icon
description1	string	The text shown for the badge

¹ A numbered badge has {n} replaced by the caller’s number

Badge inventory object

Structure

Field	Type	Description
badges1	array[built-in badge object]	Every built-in badge the caller owns
catalog2	array[catalog badge object]	One page of the catalog badges the caller owns
next_cursor3	?snowflake	The after value of the next page, or null on the last page

¹ At most six entries, never paged, in the order of Built-in badge keys

² In ascending badge ID order. A badge that was removed from the catalog is left out, so a page can hold fewer entries than limit while more remain

³ The ID of the last badge on the page

Example

{
  "badges": [
    {"source": "flag", "key": "bug_hunter", "visible": true},
    {"source": "premium", "key": "premium", "visible": false}
  ],
  "catalog": [
    {
      "source": "catalog",
      "badge_id": "1215712461409427456",
      "visible": true,
      "icon": "9f3c2b1a",
      "description": "Pioneer #1234"
    }
  ],
  "next_cursor": null
}

List my badges

GET/v1/users/@me/badges

Returns the caller’s badge inventory. Read the next page of catalog badges with next_cursor as after, and stop when next_cursor is null. Every page repeats the built-in badges.

Query parameters

Micup rejects any other query parameter with 400 INVALID_FORM_BODY.

Field	Type	Description
after?	snowflake	The cursor selecting catalog badges with IDs above this badge ID
limit?	integer	The maximum number of catalog badges to return (1-100, default 50)

Response

Status	Body	Condition
200	badge inventory object	The inventory was returned

Rate limit

60 requests per minute for each authenticated user, on the user:badge:inventory bucket.

Change badge visibility

PATCH/v1/users/@me/badges

Shows or hides one badge the caller owns. Returns 204 with an empty body.

The route works only while the instance has badge inventory settings turned on. Otherwise it returns 403 MISSING_PERMISSIONS and changes nothing.

JSON body

Micup rejects any other field with 400 INVALID_FORM_BODY.

Field	Type	Description
badge1	string	A built-in badge key or the ID of a catalog badge
visible	boolean	Whether the badge shows to other readers

¹ A catalog badge ID is a positive decimal number of at most 19 digits

Response

Status	Body	Condition
204	empty	The visibility was set
403	error response	Badge inventory settings are turned off and the request returns MISSING_PERMISSIONS
404	error response	The caller does not own the badge and the request returns NOT_FOUND

Side effects

A built-in badge change sends User Update to the caller’s sessions. A catalog badge change sends no Gateway event; the next profile read shows the new state.

Rate limit

30 requests per minute for each authenticated user, on the user:badge:visibility bucket.