A client that knows only an instance's origin starts with get instance discovery , which returns the API, Gateway and media URLs, the enabled features and the limits. Every route on this page works without a token.
The public description of one instance.
Field Type Description codename? string The protocol generation the instance speaks api_code_version integer The API code version, which goes up when clients need to change their behavior endpoints instance endpoints objectPublic service URLs captcha captcha configuration objectCAPTCHA configuration features instance features objectInstance-wide feature switches gif GIF provider objectThe GIF provider and its attribution rule sso SSO status objectSingle sign-on state registration registration policy objectWho can register community community policy objectCommunity and direct message policy services service availability objectOptional integrations that are available limits limit configuration objectLimit rules and trait names push push configuration objectWeb Push identity app_public public application configuration objectBranding, setup state and legal links age_policy? age policy objectRegional age policy notice? ?instance notice object The current notice from the instance admins, or null guild_badges?1 array[guild badge object] The first custom badges that guilds can show next to their name, in display order (at most 100) guild_badges_partial? boolean True when the instance has more guild badges than guild_badges lists custom_badges_version? string The badge catalog version. It changes whenever a badge is created, edited, deleted or moved built_in_guild_badge_images? built-in guild badge images objectThe images the instance shows in place of the built-in guild badges hidden_built_in_guild_badges?2 array[string] The built-in guild badges the instance doesn't show: any of verified, partnered and discoverable voice_origins? array[string] The origin of every voice server endpoint, such as wss://voice.example.com, for content security policies (at most 1000)
1 An instance can have any number of guild badges. Discovery lists the first 100 in display order, and List guild badges serves every one. A client that knows only guild_badges can't show a badge past the first 100
2 Guilds keep the feature behind a hidden badge, so a discoverable guild is still listed in discovery. When a guild has more than one of these badges, clients show the next one that isn't hidden
A custom badge that instance admins give to guilds. A guild lists the badges it has in badge_ids. Clients look up the IDs they don't know with List guild badges , skip the IDs it leaves out, and show the badges in ascending position order.
Field Type Description id snowflake The ID of the badge name string The name of the badge description ?string The tooltip text under the name, or null asset_url string The badge image as WebP from the media proxy. Add a size query parameter to get it at the size you draw it href ?string The https URL a click opens, or null position? string The display position as a 64-bit integer string. Older instances leave it out, and clients keep the guild_badges order
A client can show guild badges without holding the whole catalog.
Keep the badges from guild_badges and the custom_badges_version of the discovery document.
For each guild, look up the IDs in badge_ids that you don't know, in batches of up to 100, with ids and version set.
Remember the IDs the response leaves out, and don't ask for them again while the version stays the same.
When discovery or a lookup returns a newer version, forget the badges you looked up and ask again when you need them.
An instance without custom_badges_version doesn't have List guild badges . Use guild_badges alone and fetch discovery again for an unknown ID.
Instance admins can replace the artwork of the built-in guild badges. When a field has a URL, draw that image wherever the badge appears and keep the badge's usual tooltip. When it's null, draw the built-in artwork.
Field Type Description verified ?string The image for the verified badge, as WebP from the media proxy, or null partnered ?string The image for the partnered badge, or null discoverable ?string The image for the discoverable badge, or null
A short message from the instance admins, such as planned maintenance, that people can dismiss.
Field Type Description id string The ID of this version of the notice, which changes when any other field changes message string The notice text (1-1000 characters) url ?string An http or https link shown with the notice, or null starts_at ?ISO8601 timestamp When to start showing the notice, or null to show it at once ends_at ?ISO8601 timestamp When to stop showing the notice, or null for no end
Each value is an absolute URL. Use it exactly as published, including its scheme and port.
Field Type Description api string Base URL of the client API, the same as api_client api_client string Base URL of the client API, used by the Fluxer apps api_public string Base URL of the public API, used by bots and other clients gateway string The Gateway WebSocket URL, with a ws or wss scheme media string Media Proxy base URLupload_relay? string Attachment upload relay base URL static_cdn string Static asset base URL marketing string Marketing site base URL admin string Admin app base URL invite string Invite link base URL gift string Gift link base URL webapp string Web app base URL docs? string Documentation site base URL
Value Description altcha Gated operations need an ALTCHA proof-of-work challenge none The instance needs no CAPTCHA
Send the solved challenge in the X-Captcha-Token header, as CAPTCHA handling explains.
Instance-wide switches to check before you offer a feature.
Field Type Description voice_enabled boolean Whether voice and video calls are enabled stripe_enabled boolean Whether premium purchases through Stripe billing are available premium_enabled boolean Whether the instance has a premium tier stripe_serviceable boolean Whether existing Stripe subscriptions can be managed and billed self_hosted boolean Whether the instance is self-hosted presigned_attachment_uploads boolean Whether you can request presigned attachment upload URLs emails_enabled boolean Whether the instance sends email phone_verification_enabled boolean Deprecated. Always false discovery_enabled? boolean Whether the Explore community directory is available, true when missing account_identity string How people sign in, one of the account identity modes tag_style string How usernames are tagged, one of the tag styles desktop_modules_enabled? boolean Whether the desktop app can load downloadable modules account_deletion_grace_period_hours? integer Hours between a deletion request and permanent deletion (1-8,760) identifier_first? boolean Whether sign-in starts with identify an account instant_accounts? boolean Whether register an account accepts an account with only a display name email_codes? boolean Whether send an email code works date_of_birth_step? boolean Whether accounts set their date of birth after sign-up instant_account_availability? string Whether sign-up can create an instant account, one of the instant account availability values interaction_tier? string How the account tiers apply, legacy or enforced guild_join_gate? string When joining a guild needs a verified account, off, visits_capable (only for clients that can visit guilds) or always email_delivery_state? string Whether the instance sends email and why not, one of the email delivery states verification_basis? string What an account needs to be verified, confirmed_email or local_credential
When emails_enabled is false, email verification, password recovery and IP authorization don't work.
Value Description available Sign-up can create an instant account disabled An admin turned instant accounts off captcha_off Instant accounts are on, but the CAPTCHA they need is off registration_closed Public registration is closed approval_required New accounts wait for admin approval
Value Description on The instance sends email off_username_mode The instance uses usernames and never sends email off_disabled An admin or the configuration turned email off off_incomplete Email is on, but the SMTP settings or sender address are incomplete
Value Description email People register and sign in with an email address username People register and sign in with a username, and the instance collects no email address
On a username instance, email routes return 400 EMAIL_UNAVAILABLE_ON_INSTANCE. On an email instance, username-only routes such as recover an account return 400 USERNAME_SIGN_IN_ONLY.
Value Description none Usernames are unique and have no tag, and every account that isn't a bot has the discriminator 0000 random Every account gets a random tag that can be changed
Field Type Description provider string The machine name of the GIF provider display_name string The provider name to show attribution_required boolean Whether you must show the provider's attribution next to GIF results
Check services.gif_enabled before you show a GIF picker.
Field Type Description mode string The registration mode admin_registration_urls_enabled boolean Whether register an account accepts an admin-issued registration_url_code, which works even while mode is closed
Value Description open Anyone can register and gets a session at once approval New accounts wait for admin approval before they can sign in closed Public registration is refused
Field Type Description single_community boolean Whether the instance runs as one community that every account joins single_community_guild_id ?snowflake The ID of the single community's guild, or null when single_community is false direct_messages_disabled boolean Whether direct messages are off for the whole instance friends_disabled? boolean Whether friend requests are off for the whole instance personal_notes_enabled? boolean Whether people can use personal notes. Missing means they can guild_create_access boolean Whether every account can create communities. When false, only admins and accounts with feature_guild_create can
Field Type Description gif_enabled boolean Whether the GIF picker is available youtube_enabled boolean Whether YouTube link previews are available bluesky_enabled boolean Whether Bluesky connections are available
Field Type Description public_vapid_key ?string The Web Push VAPID public key, or null when Web Push isn't set up delivery_mode? string How push notifications get to devices, direct, external_relay or hybrid event_resolution_path? string The API path to call to get the payload of a push event external_relay_url? ?string The URL of the external push relay, or null relay_signing_key_hashes? ?array[string] Hashes of the keys the external push relay signs with, or null
The rules you evaluate to work out the limits for an account or a guild.
Field Type Description version integer The format version, always 2 traitDefinitions array[string] The trait names the instance declares rules array[limit rule object] The rules to evaluate defaultsHash string A hash of the release's default limit values, which changes when a release changes them
Each rule lists the keys that differ from the release defaults, plus max_guild_emojis, max_guild_stickers and their aliases whenever the rule sets them. The document doesn't include the defaults, and your client needs its own copy of them. To resolve limits, follow these steps.
Start with the default value of every limit key .
Sort the rules by the number of traits and guild features in their filters, fewest first, keeping the published order for ties.
Skip a rule unless every trait and guild feature it lists is present. You supply the account's traits and the guild's features yourself.
Expand the rule by giving every key it doesn't list the default value.
A rule with no filters sets each key to its value. A rule with filters raises each key to its value when that is higher.
Each key's scope decides whether a rule applies it.
Scope User evaluation Guild evaluation user Applied Applied only when the rule has no guild feature filter guild Not applied Applied when the rule has a guild feature filter or no trait filter both Applied Applied
Use the resolved values to show limits in your UI. The API still checks every limit and returns the endpoint's own error when a request goes over one.
Field Type Description id string The rule ID filters? limit filters objectWhat selects the rule, omitted when it always matches overrides map[string, integer] Values keyed by limit key . Negative values are ignored
" filters " : { " traits " : [ " premium " ]},
" max_message_length " : 4000 ,
An empty or missing list adds no condition.
Field Type Description traits? array[string] Trait names that must all be present guildFeatures? array[string] Guild feature names that must all be present
A feature_ key is 1 when the feature is available and 0 when it isn't. The scope of each key is in parentheses.
Value Description avatar_max_size Maximum avatar upload size in bytes, up to 104857600 (user) emoji_max_size Maximum emoji upload size in bytes, up to 104857600 (guild) feature_animated_avatar Animated avatar uploads (user) feature_animated_banner Animated banner uploads (user) feature_custom_discriminator Choosing a custom discriminator, ignored with the none tag style (user) feature_custom_notification_sounds Custom notification sounds (user) feature_early_access Beta features (user) feature_global_expressions Using expressions in every guild (user) feature_guild_create Creating communities while the instance restricts it (user) feature_higher_video_quality Higher video streaming quality (user) feature_per_guild_profiles A different profile in each guild (user) feature_voice_entrance_sounds A sound when joining voice (user) guild_visit_history_days_unverified Days of history an unverified account sees while visiting a guild (user) max_attachment_file_size Maximum size of each attachment in bytes (user and guild) max_attachments_per_message Maximum attachments per message (user and guild) max_bio_length Maximum characters in a bio, at most 320 (user) max_bookmarks Maximum bookmarked messages (user) max_channels_per_category Maximum channels per category (guild) max_custom_backgrounds Maximum custom profile backgrounds (user) max_embeds_per_message Maximum embeds per message (user and guild) max_favorite_meme_tags Maximum meme tags to track (user) max_favorite_memes Maximum favorite memes (user) max_group_dm_recipients Maximum members per group DM (user) max_group_dms_per_user Maximum group DMs a user can own (user) max_guild_channels Maximum channels per guild, counting forum and media channels but not threads (guild) max_guild_emojis Maximum emojis per guild (guild) max_guild_emojis_animated Alias of max_guild_emojis for older clients (guild) max_guild_emojis_animated_more Alias of max_guild_emojis for older clients (guild) max_guild_emojis_static Alias of max_guild_emojis for older clients (guild) max_guild_emojis_static_more Alias of max_guild_emojis for older clients (guild) max_guild_invites Maximum active invites per guild (guild) max_guild_members Maximum members per guild (guild) max_guild_roles Maximum roles per guild (guild) max_guild_stickers Maximum stickers per guild (guild) max_guild_stickers_more Alias of max_guild_stickers for older clients (guild) max_guild_visits Maximum guilds a user can visit at once, halved for unverified accounts (user) max_guilds Maximum guilds a user can join (user) max_message_length Maximum characters per message (user and guild) max_private_channels_per_user Maximum DM channels per user (user) max_reactions_per_message Maximum distinct reactions per message (guild) max_relationships Maximum friends and blocked users (user) max_screen_share_bitrate Highest screen share bitrate in bits per second, 1000000 to 50000000 (user) max_users_per_message_reaction Maximum users per reaction on a message (guild) max_voice_message_duration Maximum voice message length in seconds (user and guild) max_webhooks_per_channel Maximum webhooks per channel (guild) max_webhooks_per_guild Maximum webhooks per guild (guild) sticker_max_size Maximum sticker upload size in bytes, up to 104857600 (guild)
Threads and forums have fixed limits, listed under thread lifecycle , thread members and forum channel fields .
What a client needs before anyone signs in.
Field Type Description product_name string The instance name icon_url ?string App icon URL, or null symbol_url ?string Compact app symbol URL, or null logo_url ?string App logo URL, or null wordmark_url ?string App wordmark URL, or null favicon_url ?string Favicon URL, or null favicon_dark_url ?string Favicon URL for a dark color scheme, or null to use favicon_url theme_color ?string Brand color as lowercase #rrggbb, or null status_page_url ?string Status page URL, or null status_page_instatus boolean Whether the status page is an Instatus page browsers can read. Clients show its incidents only when this is true status_page_incident_history_url ?string Status page incident history URL, or null premium_product_name string The name of the premium tier, Premium unless an admin sets one premium_info_url ?string URL of a page about the premium tier, or null sign_in_backdrop_url ?string Image shown behind the sign-in screens, or null for the default custom_css ?string CSS the web and desktop app apply before the person's own theme, except on sign-in pages, or null upload_limit_message ?string Markdown shown when a file is over the upload limit, or null for the default text trusted_domains string[] Extra domains whose links open without a warning. Entries are hostnames, and a *. prefix also covers subdomains
Field Type Description configured boolean Whether setup is finished admin_url ?string The admin app URL to finish setup in, or null account_identity_locked? boolean Whether the sign-in method can no longer change account_identity_lock_reason? ?string One of the account identity lock reasons , or null while the method can change setup_token_required? boolean Whether register an account needs setup_token
account_identity_locked, account_identity_lock_reason and setup_token_required are sent only while a self-hosted instance isn't configured.
Value Description setup_configured Setup is finished existing_instance The instance had an admin, accounts or finished setup when its sign-in method was first set, so it stays on email admin_exists The instance has an admin account accounts_exist The instance has accounts, none of them an admin
Field Type Description terms_url ?string Terms of service URL, or null privacy_url ?string Privacy policy URL, or null guidelines_url ?string Community guidelines URL, used by report flows , or null to hide guidelines links
Field Type Description collect_date_of_birth boolean Whether sign-up asks for a date of birth, set in the admin accounts configuration
Field Type Description country_code string The ISO 3166-1 alpha-2 country code region_code ?string The ISO 3166-2 subdivision code, or null for the whole country action string restrict to need an age check, or block to refuse access
The approximate location of the request, and the places where mature content needs an age check or isn't available.
Field Type Description countryCode ?string The upper-case ISO 3166-1 alpha-2 country code, or null regionCode ?string The upper-case ISO 3166-2 subdivision code, or null latitude ?string The approximate latitude as a decimal string, or null longitude ?string The approximate longitude as a decimal string, or null ageRestrictedGeos array[geo entry object] Places where mature content needs an age check ageBlockedGeos array[geo entry object] Places where mature content isn't available
When the location is unknown, all four location fields are null. Match countryCode and regionCode against the geo lists yourself.
Field Type Description countryCode string The ISO 3166-1 alpha-2 country code regionCode ?string The ISO 3166-2 subdivision code, or null for the whole country
GET/.well-known/fluxerUnauthenticated Returns the instance discovery object . The response has ETag and Last-Modified headers, and a request with a matching If-None-Match or If-Modified-Since gets 304 with no body.
Status Body Condition 200 instance discovery objectThe discovery document was returned 304 None The document hasn't changed
The rate limit is 60 requests per minute, on the instance:info bucket.
GET/v1/instance/badgesUnauthenticated Returns custom guild badges in display order. Send ids to look up the badges of some guilds, or page through every badge with after and limit. User badges aren't listed here. They come back in each profile instead.
Field Type Description ids? string Up to 100 badge IDs separated by commas. Can't be sent with after after? string The next value of the previous page limit? integer How many badges to return when paging (1-200, default 100) version? string The custom_badges_version the client holds
Field Type Description version string The current badge catalog version badges array[guild badge object] The badges in display order. IDs that are unknown, deleted or user badges are left out next ?string Send this as after to get the next page, or null on the last page and for a lookup by ids
Request Cache-Controlversion is the current versionpublic, max-age=86400, immutableno version, or an older one public, max-age=60, must-revalidate
The response has an ETag header, and a request with a matching If-None-Match gets 304 with no body. A response read while the catalog changes gets the short lifetime and no ETag. The version also changes when the instance moves to a new media URL, because every asset_url changes with it.
Status Body Condition 200 response body The badges were returned 304 None The badges haven't changed 400 error response INVALID_FORM_BODY for a bad parameter, a cursor from another list, or ids sent with after
The rate limit is 60 requests per minute, on the instance:badges bucket. A request with a valid token counts against the account, and a request without one counts against the IP address.
GET/v1/ipUnauthenticated Returns the geolocation object for your IP address.
Status Body Condition 200 geolocation objectThe lookup ran, even if it found no location
The rate limit is 30 requests per minute, on the ip:geo_lookup bucket.
POST/v1/instance/setup/token-checksUnauthenticated Checks a setup token without using it up.
Field Type Description setup_token string The setup token (1-256 characters)
Status Body Condition 204 None The token is correct, or the instance needs no setup token 400 error response The setup token is missing or wrong 429 rate limit response Too many requests, or too many wrong tokens from your IP address
The rate limit is 10 requests per minute, on the instance:setup:token_check bucket.
PUT/v1/instance/setup/account-identityUnauthenticated Sets how people sign in on a new self-hosted instance and, for email, whether usernames have tags. Returns an account identity object. It works until one of the account identity lock reasons applies, such as setup being finished or the first account existing. Send setup_token while setup_token_required is true in the public setup state .
Field Type Description mode string The account identity mode tag_style? string One of the tag styles , none by default and always none for username setup_token? ?string The setup token (1-256 characters)
Status Body Condition 200 account identity objectThe sign-in method was saved 400 error response TAG_STYLE_REQUIRES_EMAIL_SIGN_IN for random with username, or the setup token is missing or wrong409 error response ACCOUNT_IDENTITY_LOCKED when the sign-in method can no longer change423 error response GENERAL_ERROR when another registration or setup call held the setup lock for 15 seconds. Retry after Retry-After429 rate limit response Too many requests, or too many wrong tokens from your IP address
The rate limit is 10 requests per minute, on the instance:setup:account_identity bucket.
GET/v1/openapi.jsonUnauthenticated Returns the instance's OpenAPI 3.1 document as JSON. Its server URL is the api_client endpoint followed by /v1.
Status Body Condition 200 OpenAPI 3.1 document The document was returned
The rate limit is 60 requests per minute, on the instance:info bucket.
