Current user
These routes read and change the account that made the request, a user object. Every route except Get current user needs a user session and doesn't accept bot or OAuth2 tokens. Changing credentials and the account lifecycle routes need sudo mode.
Guild entry object
Section titled “Guild entry object”The guild an account joined or is visiting after signing up with an invite.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| guild_id | snowflake | The guild the account entered |
| mode | string | member when the account joined, visit when it is visiting without joining |
Date of birth result object
Section titled “Date of birth result object”Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| user | user object | The updated account |
| entry | ?guild entry object | The guild to open next, or null |
Email code delivery object
Section titled “Email code delivery object”Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| code_expires_at | ISO8601 timestamp | When the emailed code stops working, 10 minutes after sending |
| resend_available_at | ISO8601 timestamp | When another code can be requested, 30 seconds after sending |
Claim result object
Section titled “Claim result object”Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| next_step | string | confirm_email when the emailed code still has to be entered, otherwise none |
| user | user object | The updated account |
| code_expires_at?1 | ISO8601 timestamp | When the emailed code stops working |
| resend_available_at?1 | ISO8601 timestamp | When another code can be requested |
1 Present only when next_step is confirm_email
Get current user
Section titled “Get current user”GET/v1/users/@meReturns the current user object. An OAuth2 bearer needs the identify scope and gets email only with the email scope.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | user object | The account was returned |
| 403 | error response | MISSING_OAUTH_SCOPE when a bearer lacks the identify scope |
The rate limit is 40 requests per 10 seconds, on the user:settings:get bucket, shared with Get current user settings.
Modify current user
Section titled “Modify current user”PATCH/v1/users/@meChanges the account and returns the updated user object. A different username or discriminator, new_password and email_token need sudo verification for a claimed account.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| username?1 | string | Username (1-32 ASCII letters, digits or underscores) |
| discriminator?2 | string | integer | Discriminator (1-4 decimal digits) |
| global_name? | ?string | Display name (1-32 characters), or null to clear |
| email?3 | string | Always rejected, use email_token |
| new_password?4 | string | New password (8-256 characters) |
| password? | string | Current password (8-256 characters) |
| avatar?5 | ?string | Base64-encoded avatar image, or null to clear |
| banner?5 6 | ?string | Base64-encoded banner image, or null to clear |
| bio?7 | ?string | Biography (1-320 characters), or null to clear |
| pronouns? | ?string | Pronouns (1-40 characters), or null to clear |
| accent_color? | ?integer | Packed 24-bit RGB color (0-16777215), or null to clear |
| timezone?8 | ?string | IANA timezone identifier (1-128 characters), or null to clear |
| timezone_privacy_flags? | integer | Profile field privacy flags for the timezone |
| hidden_profile_badges?12 | array[string] | The full list of badge keys to hide from other people, at most 1008 |
| premium_badge_hidden?13 | boolean | Deprecated. Use the hidden badge list |
| premium_badge_masked? | boolean | Whether to show a lifetime badge as an ordinary subscription badge |
| premium_badge_timestamp_hidden? | boolean | Whether to hide the premium activation time |
| premium_badge_sequence_hidden?13 | boolean | Deprecated. Use the hidden badge list |
| premium_enabled_override?9 | boolean | Whether a staff override grants premium entitlements |
| has_dismissed_premium_onboarding?10 | boolean | Whether the premium onboarding flow was dismissed |
| has_unread_gift_inventory?11 | boolean | Whether the gift inventory has unread items |
| mention_flags? | integer | Reply mention preference, one of 0, 1 or 2 |
| email_token? | string | Email token (1-256 characters) from verify new email |
| mfa_method? | string | Sudo mode method, one of totp, webauthn or email_code |
| mfa_code? | string | Authenticator or backup code (1-32 characters) |
| webauthn_response? | WebAuthn assertion object | WebAuthn assertion |
| webauthn_challenge? | string | WebAuthn challenge (1-256 characters) |
| email_code_ticket? | string | The ticket from send a sudo email code (1-128 characters) |
| email_code? | string | The 6-digit code from that email |
1 Can't be everyone or here and can't contain fluxer or system message. On an instance with the none tag style, a name another account has in any letter case returns USERNAME_ALREADY_TAKEN
2 Without a username, needs the custom discriminator entitlement or returns CHANGING_DISCRIMINATOR_REQUIRES_PREMIUM. A taken pair returns TAG_ALREADY_TAKEN. On an instance with the none tag style the discriminator is always 0000 and any other value returns DISCRIMINATOR_NOT_SUPPORTED_ON_INSTANCE
3 Returns EMAIL_MUST_BE_CHANGED_VIA_TOKEN, and INVALID_EMAIL_FORMAT when the value is not an address
4 A claimed account that already has a password also sends the current password or gets PASSWORD_NOT_SET. A breached password returns PASSWORD_IS_TOO_COMMON when the instance checks for them
5 Can start with a data:...;base64, prefix
6 Any non-null value needs the animated banner entitlement or returns BANNERS_REQUIRE_PREMIUM
7 The max_bio_length instance limit also applies and returns CONTENT_EXCEEDS_MAX_LENGTH
8 An unknown identifier returns INVALID_TIMEZONE_IDENTIFIER. A first timezone without timezone_privacy_flags is visible to EVERYONE
9 Needs the STAFF flag or returns 403 MISSING_ACCESS
10 Only true has an effect
11 Only false has an effect
12 Replaces the saved list. A key that is neither a built-in badge kind nor custom:{id} returns INVALID_FORM_BODY, and keys of custom badges that no longer exist are dropped
13 true adds keys to hidden_profile_badges and false removes them: plutonium, visionary and premium for premium_badge_hidden, and visionary_number for premium_badge_sequence_hidden. operator_pass_badge_hidden does the same for operator_pass. All three are ignored when the request also sends hidden_profile_badges
While interaction_tier is legacy (account tiers), an unverified account gets 403 PROFILE_EMAIL_VERIFICATION_REQUIRED when it changes the username, discriminator, display name, avatar, banner, biography, pronouns, accent color, timezone, timezone privacy or a premium badge field. In that mode an unclaimed account can only send new_password, has_dismissed_premium_onboarding, has_unread_gift_inventory, email_token and the sudo fields, and any other field returns UNCLAIMED_ACCOUNTS_CAN_ONLY_SET_EMAIL_VIA_TOKEN. On an instance where people sign in with a username, new_password can come with username to claim the account in one request.
In enforced mode an unclaimed account on an email instance that sends new_password without email_token gets 400 USE_CLAIM_ROUTE.
A limited account can't change profile fields and gets 403 ACCOUNT_LIMITED.
While the instance enforces single sign-on, an account linked to the provider that sends new_password or email_token gets 403 SSO_REQUIRED.
Images and blocklists
Section titled “Images and blocklists”Avatars and banners can be PNG, JPEG, WebP, GIF, APNG, AVIF, HEIC, HEIF, JPEG XL or SVG, up to the avatar_max_size limit (10485760 bytes by default). Other formats return INVALID_IMAGE_FORMAT and larger images return IMAGE_SIZE_EXCEEDS_LIMIT. An animated avatar needs the animated avatar entitlement or returns ANIMATED_AVATARS_REQUIRE_PREMIUM.
A username, display name, biography or pronouns that matches the instance blocklist returns 403 CONTENT_BLOCKED. STAFF accounts skip the profile blocklist but not the phrase and URL blocklists.
Change limits
Section titled “Change limits”A denied change returns 400 INVALID_FORM_BODY with the validation code.
| Change | Allowance | Validation code |
|---|---|---|
| Username or discriminator | 5 per 3 hours | USERNAME_CHANGED_TOO_MANY_TIMES |
| Biography | 25 per 30 minutes | BIO_CHANGED_TOO_MANY_TIMES |
| Pronouns | 25 per 30 minutes | PRONOUNS_CHANGED_TOO_MANY_TIMES |
| Accent color | 25 per 30 minutes | ACCENT_COLOR_CHANGED_TOO_MANY_TIMES |
| Avatar | 25 per 30 minutes | AVATAR_CHANGED_TOO_MANY_TIMES |
| Banner | 25 per 30 minutes | BANNER_CHANGED_TOO_MANY_TIMES |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | user object | The account was updated |
| 200 | user object with the password change completion fields | A password change replaced the session |
| 400 | error response | The body, image, tag, password, entitlement, change limit or sudo proof is invalid |
| 403 | error response | Email verification, sudo verification or STAFF is needed, or content is blocked |
Fluxer sends User Update to the account.
The rate limit is 20 requests per minute, on the user:update bucket.
Set date of birth
Section titled “Set date of birth”PUT/v1/users/@me/date-of-birthSets the date of birth of an account that has none and returns a date of birth result object. A date of birth can't be changed once set.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| date_of_birth1 | string | The date of birth as YYYY-MM-DD |
1 A date that doesn't exist, is today or later, or is more than 120 years ago returns INVALID_DATE_OF_BIRTH_FORMAT
The minimum age follows the region of the client IP address, as in register an account. A person below it gets 403 ACCOUNT_BELOW_MINIMUM_AGE, and the account is closed and deleted after 72 hours.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | date of birth result object | The date of birth was set |
| 400 | error response | The date is invalid |
| 403 | error response | The person is below the minimum age |
| 404 | error response | The instance doesn't collect date of birth |
| 409 | error response | The account already has a date of birth |
Fluxer sends User Update, and User Settings Update when settings still on their defaults change to match the age.
The rate limit is 5 requests per hour, on the user:date_of_birth bucket.
Claim an account
Section titled “Claim an account”POST/v1/users/@me/claimAdds an email address, and optionally a password, to an unclaimed account so it can sign in from another device. Returns a claim result object.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| email?1 | string | The email address to add |
| password?2 | string | The password to set (8-256 characters) |
1 Needed on an email instance or the field code EMAIL_IS_REQUIRED is returned. Ignored on a username instance. An address on another account returns EMAIL_ALREADY_IN_USE
2 Needed when the instance uses usernames to sign in, sends no email or has verification_basis set to local_credential, unless the account has a passkey. Without it the route returns 400 PASSWORD_REQUIRED_TO_CLAIM. A breached password returns PASSWORD_IS_TOO_COMMON
On an instance that sends email, the address waits for confirm the email address. Otherwise it is confirmed at once and next_step is none.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | claim result object | The account was claimed or the address waits for its code |
| 400 | error response | The input is invalid, or ACCOUNT_ALREADY_CLAIMED |
Fluxer sends User Update, and emails the code when next_step is confirm_email.
The rate limit is 5 requests per hour, on the user:claim bucket.
Send an email confirmation code
Section titled “Send an email confirmation code”POST/v1/users/@me/email-verification/sendEmails a 6-digit code to the unconfirmed address of the account and returns an email code delivery object.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | email code delivery object | The code was sent |
| 400 | error response | USE_CLAIM_ROUTE for an unclaimed account or one without an address |
| 400 | error response | ACCOUNT_ALREADY_CLAIMED for a confirmed address |
| 400 | error response | EMAIL_CODES_UNAVAILABLE when no code can be sent |
The rate limit is 3 requests per 15 minutes, on the user:email_verification bucket.
Confirm the email address
Section titled “Confirm the email address”POST/v1/users/@me/email-verification/confirmConfirms the address with the emailed code and returns the updated user object.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| code | string | The 6-digit code from the email |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | user object | The address was confirmed |
| 400 | error response | INVALID_SIGN_IN_CODE for a wrong code, SIGN_IN_CODE_EXPIRED after 5 wrong tries, 10 minutes or an address change |
Fluxer sends User Update.
The rate limit is 10 requests per minute, on the user:email_verification:confirm bucket.
Forget authorized IPs
Section titled “Forget authorized IPs”DELETE/v1/users/@me/authorized-ipsDeletes every authorized IP record, and the next sign-in from any address needs fresh authorization. Needs sudo verification.
JSON body
Section titled “JSON body”The sudo verification object, which can be empty when you send a sudo token.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | The records were deleted |
| 403 | error response | SUDO_MODE_REQUIRED |
The rate limit is 10 requests per minute, on the user:authorized_ips:forget bucket.
Disable current account
Section titled “Disable current account”POST/v1/users/@me/disableDisables the account and keeps its data. Needs sudo verification, and the response has no X-Fluxer-Sudo-Mode-JWT header.
JSON body
Section titled “JSON body”The sudo verification object, which can be empty when you send a sudo token.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | The account was disabled |
| 403 | error response | SUDO_MODE_REQUIRED |
The rate limit is 5 requests per hour, on the user:account:disable bucket.
Schedule current account deletion
Section titled “Schedule current account deletion”POST/v1/users/@me/deleteSchedules deletion of the account and deletes every session. Needs sudo verification.
JSON body
Section titled “JSON body”The sudo verification object, which can be empty when you send a sudo token.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | The deletion was scheduled |
| 400 | error response | The account owns a guild, USER_OWNS_GUILDS |
| 409 | error response | CONFLICT when erasure has started |
Fluxer emails the account when it has an address.
The rate limit is 5 requests per hour, on the user:account:delete bucket.
Accept current policies
Section titled “Accept current policies”POST/v1/users/@me/terms-acceptanceRecords acceptance of the current terms of service and that the privacy policy was shown, and returns the updated user object.
JSON body
Section titled “JSON body”The body is an empty object.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | user object | The acceptance was recorded |
| 400 | error response | The body is not a JSON object |
Fluxer sends User Update.
The rate limit is 20 requests per minute, on the user:update bucket.
Preview profile badges
Section titled “Preview profile badges”POST/v1/users/@me/profile-badges/previewReturns the account's profile badges as others would see them with the given settings, and every badge the account holds with whether those settings hide it. Nothing is saved.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| hidden_profile_badges? | array[string] | Preview with these badge keys hidden |
| premium_badge_masked? | boolean | Preview with the premium badge masked |
| premium_badge_timestamp_hidden? | boolean | Preview with the premium badge date hidden |
| operator_pass_badge_timestamp_hidden? | boolean | Preview with the date the Operator Pass was first held hidden |
| operator_pass_badge_count_hidden? | boolean | Preview with the number of Operator Passes hidden |
A field you leave out keeps the saved value. The deprecated premium_badge_hidden, premium_badge_sequence_hidden and operator_pass_badge_hidden fields work as in Modify current user.
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| profile_badges | array[profile badge object] | The badges other people would see, in display order |
| own_badges | array[own profile badge object] | Every badge the account holds, in display order |
Own profile badge object
Section titled “Own profile badge object”A profile badge with a hidden field. A masked Visionary badge is listed as visionary here, because that is the key you hide.
| Field | Type | Description |
|---|---|---|
| key | string | The badge's identity, and the value to put in hidden_profile_badges |
| kind | string | The badge type |
| label | string | The badge description in your locale |
| asset | ?string | The badge image hash, or null for a text badge, a custom badge or a built-in badge with a replaced image |
| asset_url | ?string | The image URL of a custom badge or of a built-in badge with a replaced image |
| aspect_ratio | ?number | The image width divided by its height |
| caption | ?string | The short badge text, such as #42 |
| href | ?string | The URL a click opens |
| small_asset? | string | The image hash for 20 pixels and smaller |
| count? | ?integer | The number of Operator Passes the badge stands for |
| accessible_label? | ?string | The label for screen readers |
| details? | ?badge details object | The tooltip content |
| hidden | boolean | Whether the badge key is in the previewed hidden_profile_badges |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The badges were returned |
The rate limit is 100 requests per 10 seconds, on the user:profile::target_id bucket.
Reset current premium state
Section titled “Reset current premium state”POST/v1/users/@me/premium/resetClears every premium field on the account. You need the STAFF flag.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | The premium state was cleared |
| 403 | error response | MISSING_ACCESS without the STAFF flag |
Fluxer sends User Update.
The rate limit is 20 requests per minute, on the user:update bucket.