Guilds
A guild is a community with its own channels, roles, members, and configuration. Membership and ownership transfer live on Guild members, and channels on Guild channels.
List current user guilds and Get guild declare the guilds OAuth2 scope, and a bearer credential without that scope receives 403 MISSING_OAUTH_SCOPE. Every other route rejects a bearer credential with 403 ACCESS_DENIED.
A guild that does not exist returns 404 UNKNOWN_GUILD, and an existing guild that does not hold the caller as a member returns 403 MISSING_PERMISSIONS, so any authenticated caller can tell a missing guild from one they are not in. A guild whose stored record exists while the main Gateway reports it unknown returns 403 ACCESS_DENIED.
Fluxer screens a route whose path opens with /guilds/{guild_id} for guild availability before the operation runs. Create guild, List current user guilds, Leave guild, and Bulk delete current user’s guild messages do not have the guild in their first two path segments, so a forced-unavailable guild is still listed and can still be left.
The instance-wide content filter screens the JSON body of every POST, PUT, and PATCH route here before the route runs. A string of at least 3 characters matching the phrase blocklist, or a URL matching the URL blocklist, returns 403 CONTENT_BLOCKED. The icon, banner, splash, embed_splash, permissions, roles, channels, password, mfa_code, webauthn_response, and webauthn_challenge members are exempt. The guild name is scanned a second time inside Create guild and Modify guild, without the 3 character floor.
Guild object
Section titled “Guild object”A guild object contains the guild’s configuration. The operation that returns it decides which embedded collections and caller-specific fields it has.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the guild |
| name | string | The name of the guild (1-100 characters) |
| icon1 | ?string | Guild icon hash |
| banner2 | ?string | Guild banner hash |
| banner_width3 | ?integer | Banner width in pixels |
| banner_height3 | ?integer | Banner height in pixels |
| splash4 | ?string | Invite splash hash |
| splash_width3 | ?integer | Invite splash width in pixels |
| splash_height3 | ?integer | Invite splash height in pixels |
| splash_card_alignment | integer | Splash card alignment |
| embed_splash4 | ?string | Embedded invite splash hash |
| embed_splash_width3 | ?integer | Embedded invite splash width in pixels |
| embed_splash_height3 | ?integer | Embedded invite splash height in pixels |
| vanity_url_code | ?string | Custom invite code |
| owner_id | snowflake | The ID of the guild owner |
| system_channel_id | ?snowflake | Text channel that receives system messages |
| system_channel_flags | integer | System channel flags |
| rules_channel_id5 | ?snowflake | The ID of the rules channel |
| afk_channel_id | ?snowflake | Voice channel that inactive members are moved to |
| afk_timeout | integer | AFK timeout in seconds (60-3600) |
| features6 | array[string] | Guild features |
| verification_level | integer | Verification level |
| mfa_level | integer | MFA level |
| nsfw_level7 | integer | NSFW level |
| nsfw | boolean | Whether the guild is marked as adult content |
| content_warning_level | integer | Guild content warning level |
| content_warning_text8 | ?string | Guild content warning text (max 200 characters) |
| explicit_content_filter | integer | Guild explicit content filter level |
| default_message_notifications | integer | Default message notification level |
| disabled_operations9 | integer | Disabled guild operations |
| message_history_cutoff10 | ?ISO8601 timestamp | Earliest message visible to a member without READ_MESSAGE_HISTORY |
| permissions?11 | decimal string | Caller permissions in the guild |
| roles?12 | array[guild role object] | Guild roles |
| emojis?12 | array[guild emoji object] | Guild emojis |
| stickers?12 | array[guild sticker object] | Guild stickers |
| channels?13 | array[channel object] | Guild channels the caller can view |
| member_count?14 | integer | Member count held by the main Gateway |
| online_count?14 | integer | Online presence count held by the main Gateway |
| approximate_member_count?15 | integer | Member count read from the main Gateway count cache |
| approximate_presence_count?15 | integer | Online presence count read from the main Gateway count cache |
1 An animated icon hash has the a_ prefix, and that prefix is removed from the returned value while the guild lacks ANIMATED_ICON
2 The field is null whenever the guild lacks BANNER, and the a_ prefix is removed from the returned value while the guild lacks ANIMATED_BANNER
3 The dimension is null whenever its own asset hash field is null
4 The field is null whenever the guild lacks INVITE_SPLASH
5 No operation on this page assigns the rules channel
6 The set has each feature at most once, and its order is not stable
7 The value is derived from nsfw, so it is 3 when nsfw is true and 0 otherwise
8 A null value means the client renders the localised default warning text for the guild
9 Written only through the Admin API
10 The cutoff is evaluated only for a member that lacks READ_MESSAGE_HISTORY. A null value denies that member every message in the guild, and a set value exposes messages created at or after the timestamp
11 Only List current user guilds populates this field, and only when its permission lookup succeeds. The value is the complete mask the caller’s roles grant
12 Only Get guild populates this field
13 Only Get guild populates this field, and the array is filtered to the channels the caller can currently view
14 Only Get guild populates these two fields, and both are computed from the guild’s live main Gateway state
15 Only List current user guilds populates these two fields, and only when with_counts is true. A guild whose counts are not currently held reports 0 for both
Example
Section titled “Example”{ "id": "1489002177550843904", "name": "Ada's Workshop", "icon": "a_9f2c1d4e", "banner": null, "splash": null, "vanity_url_code": "workshop", "owner_id": "1489002177550843905", "system_channel_id": "1489002177550843907", "system_channel_flags": 0, "afk_channel_id": null, "afk_timeout": 300, "features": ["ANIMATED_ICON", "BANNER", "VANITY_URL"], "verification_level": 1, "mfa_level": 0, "nsfw_level": 0, "nsfw": false, "content_warning_level": 0, "content_warning_text": null, "explicit_content_filter": 1, "default_message_notifications": 1, "disabled_operations": 0, "message_history_cutoff": null}Partial guild object
Section titled “Partial guild object”A partial guild object is the smaller guild shape that appears inside invite payloads. It has identity and presentation fields only, and the feature-gated asset rules of the complete guild object apply to it unchanged.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| id | snowflake | The ID of the guild |
| name | string | The name of the guild |
| icon1 | ?string | Guild icon hash |
| banner2 | ?string | Guild banner hash |
| banner_width3 | ?integer | Banner width in pixels |
| banner_height3 | ?integer | Banner height in pixels |
| splash4 | ?string | Invite splash hash |
| splash_width3 | ?integer | Invite splash width in pixels |
| splash_height3 | ?integer | Invite splash height in pixels |
| splash_card_alignment | integer | Splash card alignment |
| embed_splash4 | ?string | Embedded invite splash hash |
| embed_splash_width3 | ?integer | Embedded invite splash width in pixels |
| embed_splash_height3 | ?integer | Embedded invite splash height in pixels |
| features5 | array[string] | Guild features |
1 An animated icon hash has the a_ prefix, and that prefix is removed from the returned value while the guild lacks ANIMATED_ICON
2 The field is null whenever the guild lacks BANNER, and the a_ prefix is removed from the returned value while the guild lacks ANIMATED_BANNER
3 The dimension is null whenever its own asset hash field is null
4 The field is null whenever the guild lacks INVITE_SPLASH
5 The set has each feature at most once, and vanity_url_code is never part of this representation
Example
Section titled “Example”{ "id": "1489002177550843904", "name": "Ada's Workshop", "icon": "a_9f2c1d4e", "banner": null, "splash": null, "splash_card_alignment": 0, "embed_splash": null, "features": ["ANIMATED_ICON", "BANNER"]}Guild creation template object
Section titled “Guild creation template object”A creation template describes the roles and channels that Create guild creates. Fluxer remaps its template-local identifiers to newly allocated guild snowflakes during creation. Every template-local identifier is compared as its decimal string form, so the integer 1 and the string "1" name the same entity.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| name1 | string | Template name |
| description?1 | ?string | Template description |
| verification_level?2 | integer | Verification level, defaulting to 0 |
| default_message_notifications?2 | integer | Default message notification level, defaulting to 0 |
| explicit_content_filter?2 | integer | Guild explicit content filter level, defaulting to 0 |
| system_channel_id?3 | ?decimal string | integer | Template-local ID of the text channel that becomes the system channel |
| afk_timeout?2 | integer | AFK timeout in seconds, clamped to 60-3600 and defaulting to 300 |
| system_channel_flags?4 | integer | System channel flags, defaulting to 0 |
| roles5 | array[guild template role object] | Template roles (max 250) |
| channels6 | array[guild template channel object] | Template channels (max 500) |
1 The field is read and discarded. The new guild takes its name from the name of the Create guild body
2 The value is truncated to an integer and clamped into its registry range, and a missing value becomes the stated default. A non-numeric value fails validation and returns 400 INVALID_FORM_BODY
3 An identifier that resolves to no text channel in the same template, and an absent or null value, all fall back to the template’s first text channel. A template with no text channel receives a root text channel named general, which becomes the system channel
4 Every bit outside the registry is discarded
5 A template with more than 250 roles is rejected with 400 GUILD_TEMPLATE_INVALID. The ceiling counts the submitted array, and the everyone role is created on top of it, so 250 template roles that name no everyone role produce a guild holding 251
6 A template with more than 500 channels is rejected with 400 GUILD_TEMPLATE_INVALID
Guild template role object
Section titled “Guild template role object”Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| id1 | decimal string | integer | Template-local role ID |
| name?2 | ?string | Role name, defaulting to the empty string |
| permissions?3 | decimal string | integer | Legacy role permission bitfield |
| permissions_new?3 | decimal string | integer | Preferred role permission bitfield |
| color? | integer | Role colour, defaulting to 0 |
| hoist? | boolean | Whether the role is displayed separately (default false) |
| mentionable? | boolean | Whether anyone can mention the role (default false) |
| unicode_emoji?4 | ?string | Role Unicode emoji |
1 A duplicate identifier rejects creation with 400 GUILD_TEMPLATE_INVALID
2 The role whose name is exactly @everyone supplies the permissions of the new guild’s everyone role, and when no role has that name the role whose identifier is 0 supplies them. Every remaining role is created in array order at positions 1 upward
3 permissions_new takes precedence over permissions, the value is masked to the permission bits Fluxer defines, and a value that is not a valid integer rejects creation with 400 GUILD_TEMPLATE_INVALID. An everyone role whose resolved mask is 0 receives the default permission set
4 The value is stored on the created role. The everyone role is always created with no Unicode emoji
Guild template channel object
Section titled “Guild template channel object”Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| id1 | decimal string | integer | Template-local channel ID |
| type2 | integer | Source channel type |
| name? | ?string | Channel name, defaulting to the empty string |
| topic? | ?string | Channel topic |
| position | integer | The sort position of the channel |
| parent_id?3 | ?decimal string | integer | Template-local parent category ID |
| bitrate?4 | ?integer | Voice bitrate, defaulting to 64000 for a voice channel |
| user_limit?4 | ?integer | Voice occupancy limit, defaulting to 0 for a voice channel |
| voice_connection_limit?4 | ?integer | Per-user voice connection limit, defaulting to 5 for a voice channel |
| nsfw? | boolean | Whether the channel is age restricted (default false) |
| rate_limit_per_user? | integer | Slowmode interval in seconds, defaulting to 0 |
| permission_overwrites?5 | array[guild template role permission overwrite object] | Role permission overwrites |
1 A duplicate identifier in the same template rejects creation with 400 GUILD_TEMPLATE_INVALID
2 The value 0 creates a text channel, 2 a voice channel, and 4 a category, and for an import from the other platform 5 creates a text channel and 13 a voice channel. Fluxer skips every other value, so the channel is not created
3 The identifier is applied only when it resolves to a category in the same template, and every other value leaves the channel at the guild root
4 The three voice fields are stored only on a voice channel and are null on every other channel type
5 An entry is applied only when its resolved type is 0 and its id resolves to a role in the same template, and the identifier 0 resolves to the everyone role. Fluxer skips every other entry, and a channel whose entries are all skipped is created with no overwrites
Guild template role permission overwrite object
Section titled “Guild template role permission overwrite object”Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| id | decimal string | integer | Template-local role ID |
| type1 | integer | string | Overwrite type |
| allow2 | decimal string | integer | Allowed permission bitfield |
| deny2 | decimal string | integer | Denied permission bitfield |
1 The string role resolves to 0 and the string member resolves to 1, and every other string is read as a number. Only a resolved value of 0 is applied
2 The value is masked to the permission bits Fluxer defines, and a value that is not a valid integer rejects creation with 400 GUILD_TEMPLATE_INVALID
Verification levels
Section titled “Verification levels”A verification level gates member participation. Fluxer evaluates it when a member sends a message in the guild.
| Value | Name | Description |
|---|---|---|
| 0 | NONE | No verification requirement |
| 1 | LOW1 | The account is claimed and its email address verified |
| 2 | MEDIUM | The LOW requirement, and the account is at least 5 minutes old |
| 3 | HIGH2 | The MEDIUM requirement, and the membership is at least 10 minutes old |
| 4 | VERY_HIGH3 | The account has a verified phone number |
1 A guild with DISCOVERABLE is evaluated at an effective minimum of LOW even when the stored value is NONE, and Modify guild rejects lowering a discoverable guild below LOW with 400 INVALID_FORM_BODY and the field code DISCOVERABLE_GUILD_VERIFICATION_LEVEL_TOO_LOW
2 The membership age requirement is skipped when the join timestamp cannot be read, so the level behaves as MEDIUM
3 A verified phone number is the whole requirement at this level
The guild owner, a bot, and any member holding at least one role bypass the check at every level.
MFA levels
Section titled “MFA levels”| Value | Name | Description |
|---|---|---|
| 0 | NONE | MFA is not required for moderation actions |
| 1 | ELEVATED1 | MFA is required for moderation actions |
1 Only the guild owner can change this value, the owner account needs a second factor already configured, and the change requires sudo mode
While the level is ELEVATED, a caller other than the guild owner exercises the nine elevated permissions only with an enrolled authenticator, and a bot inherits the enrolment state of its application owner. An operation that asserts an elevated permission the caller holds but cannot exercise returns 400 TWO_FACTOR_REQUIRED after the permission itself has been confirmed.
Splash card alignments
Section titled “Splash card alignments”| Value | Name | Description |
|---|---|---|
| 0 | CENTER | Centre the splash card |
| 1 | LEFT | Align the splash card to the left |
| 2 | RIGHT | Align the splash card to the right |
Guild explicit content filter levels
Section titled “Guild explicit content filter levels”A guild explicit content filter level is the guild-wide filter a moderator selects. The account setting of the same name on the user settings object is a different registry with different values.
| Value | Name | Description |
|---|---|---|
| 0 | DISABLED | Do not apply the guild explicit content filter |
| 1 | MEMBERS_WITHOUT_ROLES | Apply the filter to members without roles |
| 2 | ALL_MEMBERS | Apply the filter to all members |
Default message notification levels
Section titled “Default message notification levels”| Value | Name | Description |
|---|---|---|
| 0 | ALL_MESSAGES | Notify for all messages by default |
| 1 | ONLY_MENTIONS | Notify only for mentions by default |
NSFW levels
Section titled “NSFW levels”| Value | Name | Description |
|---|---|---|
| 0 | SAFE | Guild is not age restricted |
| 3 | AGE_RESTRICTED | Guild is age restricted |
The registry has no other value. Fluxer derives the level from the guild’s nsfw field and never writes it directly.
Guild content warning levels
Section titled “Guild content warning levels”The guild is the last position in the resolution chain described by channel content warning levels.
| Value | Name | Description |
|---|---|---|
| 0 | INHERIT | No level is set at guild level, so a channel that inherits displays no content warning |
| 1 | CONTENT_WARNING | A channel that inherits displays the guild content warning |
System channel flags
Section titled “System channel flags”| Value | Name | Description |
|---|---|---|
| 1 << 0 | SUPPRESS_JOIN_NOTIFICATIONS | Suppress member join system messages |
Every bit outside this registry is discarded when the field is written.
Disabled guild operations
Section titled “Disabled guild operations”A set bit disables the named behaviour across the guild. Only the Admin API writes the bitfield.
| Value | Name | Description |
|---|---|---|
| 1 << 0 | PUSH_NOTIFICATIONS | Disable push notifications |
| 1 << 1 | EVERYONE_MENTIONS | Disable mentions of the everyone role |
| 1 << 2 | TYPING_EVENTS | Disable typing events |
| 1 << 3 | INSTANT_INVITES | Disable instant invites |
| 1 << 4 | SEND_MESSAGE | Disable message sending |
| 1 << 5 | REACTIONS | Disable reactions |
| 1 << 6 | MEMBER_LIST_UPDATES | Disable member list updates |
Guild features
Section titled “Guild features”A feature is a capability or availability flag in the guild’s features array.
| Value | Description |
|---|---|
| ANIMATED_ICON | Guild can use an animated icon |
| ANIMATED_BANNER | Guild can use an animated banner |
| BANNER | Guild can use a banner |
| CLONE_EMOJI_DISABLED1 | The one-click emoji clone shortcut is disabled for non-members |
| CLONE_STICKER_DISABLED1 | The one-click sticker clone shortcut is disabled for non-members |
| DETACHED_BANNER1 | Guild banner is independent from its splash |
| INVITE_SPLASH | Guild can use invite splash assets |
| INVITES_DISABLED1 | Guild invite use is disabled |
| RAID_DETECTED | Raid detection is active and invites are restricted |
| TEXT_CHANNEL_FLEXIBLE_NAMES1 | Text channel names accept the flexible naming policy |
| HIDE_OWNER_CROWN1 | Guild owner crown is hidden |
| MORE_EMOJI2 | Legacy increased emoji slot allowance |
| MORE_STICKERS2 | Legacy increased sticker slot allowance |
| UNLIMITED_EMOJI3 | Guild emoji slots are effectively unlimited |
| UNLIMITED_STICKERS3 | Guild sticker slots are effectively unlimited |
| EXPRESSION_PURGE_ALLOWED | Expression assets can be purged through delete operations |
| VANITY_URL | Guild can own a custom invite code |
| DISCOVERABLE | Guild is present in public discovery |
| PARTNERED | Guild has partnered status |
| VERIFIED | Guild has verified status |
| VIP_VOICE | Guild has VIP voice capability |
| VOICE_E2EE | Guild voice channels support end-to-end encryption |
| UNAVAILABLE_FOR_EVERYONE4 | Guild is unavailable to every account |
| UNAVAILABLE_FOR_EVERYONE_BUT_STAFF4 | Guild is unavailable to every account without the instance staff flag |
| UNAVAILABLE_HIDDEN | Guild is hidden while it is forced unavailable |
| VISIONARY | Guild has visionary status |
| LARGE_GUILD_OVERRIDE2 | Guild is marked as a large guild |
| VERY_LARGE_GUILD5 | Guild member capacity is raised |
1 The feature is added or removed through Modify guild, as part of the complete array. Send every feature without this marker back to features exactly as the guild holds it
2 The feature changes no HTTP API behaviour. An instance can name it in a filter of the ordered limit configuration, and the stock configuration names none of the three
3 The expression operations raise the slot ceiling directly, outside the instance limit configuration
4 An authenticated request whose path opens with /guilds/{guild_id} or /channels/{channel_id}, where that channel belongs to this guild, is rejected before the operation runs with 403 MISSING_ACCESS. UNAVAILABLE_FOR_EVERYONE applies to the guild owner exactly as it applies to every other member, while UNAVAILABLE_FOR_EVERYONE_BUT_STAFF exempts an account with the instance staff flag
5 The feature raises the default max_guild_members limit from 1000000 to 10000000 before the ordered limit configuration is consulted, so the raised ceiling applies even when no configured rule names the feature
Custom invite URL object
Section titled “Custom invite URL object”A custom invite URL object reports the guild’s current custom invite code and how many times the invite behind it has been used. Get guild custom invite URL returns it.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| code | ?string | Current custom invite code |
| uses1 | integer | Use count of the invite backing the current code |
1 The value is 0 when the guild holds no code and when the backing invite can no longer be resolved
Example
Section titled “Example”{ "code": "workshop", "uses": 128}Custom invite URL selection object
Section titled “Custom invite URL selection object”A custom invite URL selection object reports the code the guild holds after a write. Modify guild custom invite URL returns it.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| code | ?string | Custom invite code held by the guild after the request (2-32 characters) |
Sudo verification fields
Section titled “Sudo verification fields”These fields prove sudo mode when an operation requires it. A caller can also supply an existing proof through the X-Fluxer-Sudo-Mode-JWT request header.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| password?1 | string | Current account password |
| mfa_method?2 | string | MFA method, either totp or webauthn |
| mfa_code? | string | Authenticator code when the method is totp (1-32 characters) |
| webauthn_response? | WebAuthn assertion object | Assertion when the method is webauthn |
| webauthn_challenge? | string | Challenge bound to the WebAuthn assertion |
1 The password is accepted only when the account has no second factor, and it returns the field code INVALID_PASSWORD when it does not match
2 The MFA proof is accepted only when the account has a second factor, and it returns the field code INVALID_MFA_CODE on any failure
A bot credential satisfies sudo mode without any proof. An account that has no password hash and no second factor also satisfies it without any proof. Every other account that supplies no usable proof receives 403 SUDO_MODE_REQUIRED, whose error object has has_mfa and a methods object reporting whether totp and webauthn are available.
Fluxer issues a newly generated proof in the X-Fluxer-Sudo-Mode-JWT header of the success response, and only for an account that has a second factor. A proof supplied on the request is echoed back in that same header.
Create guild
Section titled “Create guild”POST/v1/guildsCreates a guild owned by the caller. Requires a user session credential. Returns a guild object on success. Emits Guild Create and User Settings Update Gateway events to the owner.
Limitations
Section titled “Limitations”- A bot credential is rejected with 400
BOTS_CANNOT_CREATE_GUILDS. - An unclaimed account is rejected with 400
UNCLAIMED_ACCOUNT_CANNOT_CREATE_GUILDS. - An account without a verified email address is rejected with 403
GUILD_CREATION_EMAIL_VERIFICATION_REQUIRED. - A caller already at the configured guild limit is rejected with 400
MAX_GUILDS. - While the instance’s single community policy is active, every caller is rejected with 400
SINGLE_COMMUNITY_CANNOT_CREATE_GUILDS.
Fluxer decides the single community refusal first, so it precedes the email, bot, unclaimed, and guild limit failures.
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| name1 | string | Guild name (1-100 characters) |
| icon?2 | ?base64 string | Guild icon |
| empty_features?3 | boolean | Whether to create the guild with no features (default false) |
| template? | guild creation template object | Roles and channels to provision for the new guild |
1 Fluxer trims the value before it measures the length bound
2 The field accepts raw base64, or a data URL whose payload is everything after the first comma
3 When false the guild is created holding ANIMATED_ICON, ANIMATED_BANNER, BANNER, and INVITE_SPLASH
A name that satisfies the 1 to 100 character bound only before normalisation is rejected with the field code STRING_LENGTH_INVALID. The normalised name is scanned against the instance phrase and URL blocklists, and a match returns 403 CONTENT_BLOCKED.
The icon base64 payload is bounded to 1 to 13981016 characters and is otherwise rejected with BASE64_LENGTH_INVALID, and a payload that is not valid base64 with INVALID_BASE64_FORMAT. The decoded image must fit within the instance avatar_max_size limit, which defaults to the 10 MiB ceiling, and a larger image is rejected with IMAGE_SIZE_EXCEEDS_LIMIT. PNG, JPEG, WebP, GIF, APNG, AVIF, HEIC, HEIF, JXL, and SVG are accepted. An animated AVIF is rejected with INVALID_IMAGE_FORMAT.
Without a template the guild is created with a Text Channels category holding a text channel named general, a Voice Channels category holding a voice channel named General, and an everyone role with the default permission set. The general channel becomes the system channel.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | guild object | Guild was created |
| 4001 | error response | Body, image, template, bot or unclaimed credential, configured guild limit, or single community policy rejects creation |
| 4032 | error response | Email address is unverified, or the name is blocked |
1 The error code is SINGLE_COMMUNITY_CANNOT_CREATE_GUILDS while the single community policy is active, BOTS_CANNOT_CREATE_GUILDS for a bot credential, UNCLAIMED_ACCOUNT_CANNOT_CREATE_GUILDS for an unclaimed account, MAX_GUILDS at the configured guild limit, GUILD_TEMPLATE_INVALID for a rejected template, and INVALID_FORM_BODY otherwise
2 The error code is GUILD_CREATION_EMAIL_VERIFICATION_REQUIRED for an unverified email address and CONTENT_BLOCKED for a blocked name or body string
Side effects
Section titled “Side effects”The operation creates the guild, its everyone role, its template or default channels, and the owner’s membership. A supplied icon becomes the guild icon. Fluxer adds the guild to the owner’s guild folder layout. The owner receives Guild Create for the new guild and User Settings Update with the changed folder layout. No audit log entry is recorded, and an X-Audit-Log-Reason header on this request is read and discarded.
Rate limit
Section titled “Rate limit”10 requests per minute for each authenticated user, on the guild:create bucket.
List current user guilds
Section titled “List current user guilds”GET/v1/users/@me/guildsReturns an array of guild objects, one for every guild the authenticated user is a member of. A bearer credential requires the guilds OAuth2 scope.
Query parameters
Section titled “Query parameters”| Field | Type | Description |
|---|---|---|
| before?1 | snowflake | Return guilds with a lower ID than this guild ID |
| after?1 | snowflake | Return guilds with a higher ID than this guild ID |
| limit? | integer | Maximum number returned (1-200, default 200) |
| with_counts?2 | boolean | Include approximate member and presence counts (default false) |
1 A page is always ordered by ascending guild ID whichever cursor is used, and after takes precedence when both cursors are supplied. A cursor naming a guild the caller is not a member of is ignored, so the page starts at the first guild
2 A guild whose counts cannot be fetched is returned without them
A membership whose guild record can no longer be resolved is dropped before the cursor and limit are applied, so the page still has up to limit guilds when further guilds remain. This route runs no availability screen, and a guild with UNAVAILABLE_FOR_EVERYONE is still listed.
A page within that ceiling can still omit permissions from an individual guild the lookup could not resolve.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | array[guild object] | Guilds were returned |
| 403 | error response | Bearer credential lacks the guilds scope and the request returns MISSING_OAUTH_SCOPE |
Rate limit
Section titled “Rate limit”40 requests per 10 seconds for each authenticated user, on the guild:list bucket.
Get guild
Section titled “Get guild”GET/v1/guilds/{guild_id}Returns the guild object with its roles, emojis, stickers, viewable channels, member_count, and online_count. Requires membership of the guild, and a bearer credential requires the guilds OAuth2 scope.
The response has no permissions field. Read List current user guilds for the caller’s mask.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| guild_id | snowflake | The ID of the guild |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | guild object | Guild was returned |
| 4031 | error response | Guild is unavailable, the bearer credential lacks the guilds scope, or the caller is not a member |
| 404 | error response | Guild does not exist and the request returns UNKNOWN_GUILD |
1 The error code is MISSING_ACCESS for an unavailable guild, MISSING_OAUTH_SCOPE for a missing scope, MISSING_PERMISSIONS for a non-member, and ACCESS_DENIED when the record exists while the Gateway reports the guild unknown
Rate limit
Section titled “Rate limit”100 requests per 10 seconds for each authenticated user and guild, on the guild:read::guild_id bucket.
Modify guild
Section titled “Modify guild”PATCH/v1/guilds/{guild_id}Modifies guild configuration and returns the updated guild object. Requires membership and MANAGE_GUILD. Emits a Guild Update Gateway event to every session that can see the guild.
MANAGE_GUILD is an elevated permission. While the guild MFA level is elevated, a caller other than the owner also needs an enrolled authenticator, and receives 400 TWO_FACTOR_REQUIRED without one.
Changing mfa_level to a different value additionally requires the guild owner, an owner account that already has a second factor, and sudo mode. A caller who is not the owner receives 403 MISSING_PERMISSIONS for that change even while holding MANAGE_GUILD. Sudo mode is verified before ownership, so a non-owner without a proof receives 403 SUDO_MODE_REQUIRED first.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| guild_id | snowflake | The ID of the guild |
Request headers
Section titled “Request headers”| Field | Type | Description |
|---|---|---|
| X-Fluxer-Sudo-Mode-JWT? | string | Existing sudo mode proof, read when the MFA level changes |
JSON body
Section titled “JSON body”Every field is optional. An omitted field preserves its current value, and a field explicitly set to null clears it where the type allows null.
| Field | Type | Description |
|---|---|---|
| name?1 | string | Guild name (1-100 characters) |
| icon?2 | ?base64 string | Guild icon, or null to clear it |
| system_channel_id?3 | ?snowflake | System channel ID, or null to clear it |
| system_channel_flags?4 | integer | System channel flags |
| afk_channel_id?5 | ?snowflake | AFK voice channel ID, or null to clear it |
| afk_timeout? | integer | AFK timeout in seconds (60-3600) |
| default_message_notifications? | integer | Default message notification level |
| verification_level?6 | integer | Verification level |
| mfa_level?7 | integer | MFA level |
| nsfw_level?8 | integer | Legacy NSFW level, which is translated into nsfw and the content warning level |
| nsfw?9 | boolean | Whether the guild is marked as adult content |
| content_warning_level?10 | integer | Guild content warning level |
| content_warning_text?11 | ?string | Content warning text (max 200 characters), or null for the localised default |
| explicit_content_filter? | integer | Guild explicit content filter level |
| banner?12 | ?base64 string | Guild banner, or null to clear it |
| splash?13 | ?base64 string | Static invite splash, or null to clear it |
| embed_splash?13 | ?base64 string | Static embedded invite splash, or null to clear it |
| splash_card_alignment? | integer | Splash card alignment |
| features?14 | array[string] | Complete desired guild feature set (max 100 entries) |
| message_history_cutoff?15 | ?ISO8601 timestamp | Earliest history visible without READ_MESSAGE_HISTORY, or null to deny historical access |
| password? | string | Sudo verification password |
| mfa_method? | string | Sudo verification method, either totp or webauthn |
| mfa_code? | string | Sudo verification authenticator code |
| webauthn_response? | WebAuthn assertion object | Sudo verification assertion |
| webauthn_challenge? | string | Challenge bound to the WebAuthn assertion |
1 The value is normalised and trimmed before its length is measured, and the normalised name is scanned against the instance phrase and URL blocklists, so a match returns 403 CONTENT_BLOCKED
2 The accepted encoding, byte ceiling, and format set are the ones listed by Create guild. No guild feature gates an animated icon on write, but the a_ prefix is stripped from the returned hash while the guild lacks ANIMATED_ICON
3 The channel must exist in this guild and be a text channel, and is otherwise rejected with SYSTEM_CHANNEL_MUST_BE_IN_GUILD or SYSTEM_CHANNEL_MUST_BE_TEXT
4 Every bit outside the registry is discarded
5 The channel must exist in this guild and be a voice channel, and is otherwise rejected with AFK_CHANNEL_MUST_BE_IN_GUILD or AFK_CHANNEL_MUST_BE_VOICE
6 A guild with DISCOVERABLE cannot be lowered below LOW and is rejected with the field code DISCOVERABLE_GUILD_VERIFICATION_LEVEL_TOO_LOW. That check runs before the MFA level check
7 Sending the value the guild already holds needs neither ownership nor sudo mode, and an owner without a configured second factor is rejected with the field code MUST_ENABLE_2FA_BEFORE_REQUIRING_FOR_MODS
8 The only accepted values are 0 and 3, and nsfw takes precedence when both fields are supplied. Setting 3 through this field also raises the content warning level to CONTENT_WARNING when content_warning_level is absent from the same body and the guild currently sits at INHERIT
9 The write also sets nsfw_level to 3 when true and 0 when false, and unlike nsfw_level it never changes the content warning level
10 Any value other than 1 is stored as 0
11 The value is trimmed, and a value that is empty after trimming is stored as null
12 A non-null value requires BANNER, and an animated image additionally requires ANIMATED_BANNER, otherwise the request is rejected with the field codes GUILD_BANNER_REQUIRES_FEATURE or ANIMATED_GUILD_BANNER_REQUIRES_FEATURE
13 A non-null value requires INVITE_SPLASH and is rejected with the field codes INVITE_SPLASH_REQUIRES_FEATURE or EMBED_SPLASH_REQUIRES_FEATURE. Both splash fields take static images only, so GIF and APNG are not accepted for either and an animated upload is rejected with the field code INVALID_IMAGE_FORMAT
14 Adding a feature that is not user-toggleable is rejected with the field code GUILD_FEATURE_NOT_TOGGLEABLE, while omitting a feature that is not user-toggleable leaves it in place. The user-toggleable features are INVITES_DISABLED, TEXT_CHANNEL_FLEXIBLE_NAMES, DETACHED_BANNER, CLONE_EMOJI_DISABLED, CLONE_STICKER_DISABLED, and HIDE_OWNER_CROWN
15 A timestamp earlier than the guild’s creation time or in the future is rejected with MESSAGE_HISTORY_CUTOFF_BEFORE_GUILD_CREATION or MESSAGE_HISTORY_CUTOFF_IN_FUTURE
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | guild object | Guild was modified, or the supplied values matched current state |
| 4001 | error response | Body, image, feature set, channel reference, timestamp, or sudo proof is invalid |
| 4001 | error response | Caller cannot exercise MANAGE_GUILD |
| 4032 | error response | Guild is unavailable, the name is blocked, MANAGE_GUILD or ownership is absent, or sudo mode is required |
| 4043 | error response | Guild does not exist |
1 The error code is TWO_FACTOR_REQUIRED for a caller who holds MANAGE_GUILD but cannot exercise it, and INVALID_FORM_BODY otherwise
2 The error code is MISSING_ACCESS for an unavailable guild, CONTENT_BLOCKED for a blocked name or body string, SUDO_MODE_REQUIRED when an MFA level change is unproven, and MISSING_PERMISSIONS for a non-member, a missing MANAGE_GUILD, or a non-owner changing the MFA level
3 The error code is UNKNOWN_GUILD
Side effects
Section titled “Side effects”Every successful request emits Guild Update to every session that can see the guild, and a request that writes no field still emits it.
Only a change to an audited field records a GUILD_UPDATE audit entry with the previous and new values, which in turn emits Guild Audit Log Entry Create to sessions that can read the audit log.
Removing TEXT_CHANNEL_FLEXIBLE_NAMES renames every guild text channel whose stored name does not satisfy the strict naming policy and, when at least one channel is renamed, emits one Channel Update Bulk Dispatch with every channel in the guild.
Replacing an image queues the previous asset for deletion after the change succeeds. A failed replacement rolls back the newly uploaded asset and leaves the previous image unchanged.
Rate limit
Section titled “Rate limit”20 requests per 10 seconds for each authenticated user and guild, on the guild:update::guild_id bucket.
Delete guild
Section titled “Delete guild”POST/v1/guilds/{guild_id}/deletePermanently deletes the guild and returns 204 with an empty body. Requires the guild owner and sudo mode. Emits a Guild Delete Gateway event to every member session.
Fluxer refuses a non-owner with 403 MISSING_PERMISSIONS. A bot can never own a guild, so a bot credential never satisfies the requirement.
A guild protected by an active single community policy cannot be deleted and returns 400 SINGLE_COMMUNITY_CANNOT_DELETE. Fluxer decides that refusal before the ownership check and before sudo mode is verified, so a non-owner of such a guild receives the 400 rather than the 403.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| guild_id | snowflake | The ID of the guild |
Request headers
Section titled “Request headers”| Field | Type | Description |
|---|---|---|
| X-Fluxer-Sudo-Mode-JWT? | string | Existing sudo mode proof |
JSON body
Section titled “JSON body”The body is the optional sudo verification fields. A request that already has a valid proof can omit it.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | Guild was deleted |
| 4001 | error response | Body, sudo proof, or single community policy rejects the request |
| 4032 | error response | Guild is unavailable, the caller is not the owner, or sudo mode is required |
| 4043 | error response | Guild does not exist |
1 The error code is SINGLE_COMMUNITY_CANNOT_DELETE while the policy protects this guild, and INVALID_FORM_BODY otherwise
2 The error code is MISSING_ACCESS for an unavailable guild, SUDO_MODE_REQUIRED when sudo mode is unproven, and MISSING_PERMISSIONS for a caller who is not a member or not the owner
3 The error code is UNKNOWN_GUILD
Side effects
Section titled “Side effects”Every member session receives Guild Delete before any state is removed. The operation then removes every membership, deletes each member’s guild settings, and removes the guild from each non-bot member’s folder layout, which emits User Settings Update to that member’s sessions. It deletes every invite, webhook, message, attachment, and discovery record, and then the guild itself.
No audit log entry is recorded, because the audit log is destroyed with the guild. An X-Audit-Log-Reason header on this request is read and discarded.
Rate limit
Section titled “Rate limit”10 requests per minute for each authenticated user and guild, on the guild:delete::guild_id bucket.
Leave guild
Section titled “Leave guild”DELETE/v1/users/@me/guilds/{guild_id}Removes the authenticated account’s membership and returns 204 with an empty body. Requires a current membership. Emits a Guild Member Remove Gateway event to the remaining guild sessions and a Guild Delete Gateway event to the leaving account’s own sessions.
A caller with no current membership receives 404 UNKNOWN_MEMBER whether or not the guild exists. The guild owner cannot leave and receives 400 INVALID_FORM_BODY with the field code CANNOT_LEAVE_GUILD_AS_OWNER. A guild protected by an active single community policy cannot be left and returns 400 SINGLE_COMMUNITY_CANNOT_LEAVE. Setting delete_messages requires sudo mode, which a bot credential satisfies implicitly.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| guild_id | snowflake | The ID of the guild |
Query parameters
Section titled “Query parameters”| Field | Type | Description |
|---|---|---|
| delete_messages?1 | boolean | Delete every message the caller authored in the guild before leaving (default false) |
1 The deletion runs inside this request and completes before the membership is removed. The response is sent only after every matching message is gone
Setting delete_messages also changes the failure order. Fluxer resolves the guild and proves sudo mode before it reads the membership, so a non-member of an existing guild receives 403 MISSING_PERMISSIONS rather than 404 UNKNOWN_MEMBER.
Request headers
Section titled “Request headers”| Field | Type | Description |
|---|---|---|
| X-Fluxer-Sudo-Mode-JWT? | string | Existing sudo mode proof, read only when delete_messages is true |
JSON body
Section titled “JSON body”The optional body is the sudo verification fields. It is validated on every request and used only when delete_messages is true.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 204 | empty | Membership was removed |
| 4001 | error response | Query, body, sudo proof, guild ownership, or single community policy rejects the request |
| 4032 | error response | Sudo mode is required, or the caller is not a member while delete_messages is true |
| 4043 | error response | Caller holds no membership in the guild |
1 The error code is SINGLE_COMMUNITY_CANNOT_LEAVE while the policy protects this guild, and INVALID_FORM_BODY otherwise, with the field code CANNOT_LEAVE_GUILD_AS_OWNER on guild_id for the guild owner
2 The error code is SUDO_MODE_REQUIRED when delete_messages is true and sudo mode is unproven, and MISSING_PERMISSIONS for a non-member reached through the delete_messages path
3 The error code is UNKNOWN_MEMBER, and UNKNOWN_GUILD when delete_messages is true and the guild does not exist
Side effects
Section titled “Side effects”The operation snapshots the membership’s first join time, leave time, and any active communication timeout for one year, removes the membership, and decreases the guild’s member count. For a non-bot account it also removes the guild from the account’s folder layout, which emits User Settings Update to that account’s sessions.
Remaining guild sessions receive Guild Member Remove and the leaving account’s sessions receive Guild Delete.
Fluxer leaves the guild’s read states and per-guild settings in place. The membership row is destroyed with everything on it, so the guild nickname, guild avatar, guild banner, bio, pronouns, accent colour, and roles do not survive the leave. Rejoining within the retention window restores an unexpired communication timeout and nothing else. No audit log entry is recorded, and an X-Audit-Log-Reason header on this request is read and discarded.
Rate limit
Section titled “Rate limit”10 requests per 10 seconds for each authenticated user and guild, on the guild:leave::guild_id bucket.
Bulk delete current user’s guild messages
Section titled “Bulk delete current user’s guild messages”POST/v1/users/@me/guilds/{guild_id}/messages/bulk-delete-mineDeletes every message the authenticated account has authored in the guild and returns 202 with an empty body. Requires membership and sudo mode, which a bot credential satisfies implicitly. The membership survives the request.
The deletion runs inside this request, so the 202 is sent only after every matching message in every guild channel has been removed. Each processed batch emits Message Delete Bulk in its channel.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| guild_id | snowflake | The ID of the guild |
Request headers
Section titled “Request headers”| Field | Type | Description |
|---|---|---|
| X-Fluxer-Sudo-Mode-JWT? | string | Existing sudo mode proof |
JSON body
Section titled “JSON body”The body is the optional sudo verification fields.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 202 | empty | Messages were deleted |
| 400 | error response | Body or sudo proof is invalid |
| 4031 | error response | Caller is not a member, or sudo mode is required |
| 4042 | error response | Guild does not exist |
1 The error code is MISSING_PERMISSIONS for a caller who is not a member and SUDO_MODE_REQUIRED when sudo mode is unproven
2 The error code is UNKNOWN_GUILD
Side effects
Section titled “Side effects”The operation deletes the caller’s messages in this guild’s channels in batches of at most 100 per channel. Each batch purges the messages’ attachments and emits Message Delete Bulk with that batch’s IDs to the channel. No audit log entry is recorded.
Rate limit
Section titled “Rate limit”10 requests per 10 seconds for each authenticated user and guild, on the shared guild:leave::guild_id bucket.
Get guild custom invite URL
Section titled “Get guild custom invite URL”GET/v1/guilds/{guild_id}/vanity-urlReturns the guild’s custom invite URL object. Requires membership and MANAGE_GUILD.
MANAGE_GUILD is an elevated permission. While the guild MFA level is elevated, a caller other than the owner also needs an enrolled authenticator, and receives 400 TWO_FACTOR_REQUIRED without one.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| guild_id | snowflake | The ID of the guild |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | custom invite URL object | Custom invite URL state was returned |
| 4001 | error response | Caller cannot exercise MANAGE_GUILD |
| 4032 | error response | Guild is unavailable, or MANAGE_GUILD is absent |
| 404 | error response | Guild does not exist and the request returns UNKNOWN_GUILD |
1 The error code is TWO_FACTOR_REQUIRED
2 The error code is MISSING_ACCESS for an unavailable guild and MISSING_PERMISSIONS for a non-member or a caller lacking MANAGE_GUILD
Rate limit
Section titled “Rate limit”100 requests per 10 seconds for each authenticated user and guild, on the guild:vanity_url:get::guild_id bucket.
Modify guild custom invite URL
Section titled “Modify guild custom invite URL”PATCH/v1/guilds/{guild_id}/vanity-urlSets or removes the guild’s custom invite code and returns the custom invite URL selection object. Requires membership and MANAGE_GUILD. An effective change emits a Guild Update Gateway event to every session that can see the guild.
MANAGE_GUILD is an elevated permission. While the guild MFA level is elevated, a caller other than the owner also needs an enrolled authenticator, and receives 400 TWO_FACTOR_REQUIRED without one.
A non-null code additionally requires the VANITY_URL guild feature and is otherwise rejected with the field code VANITY_URL_REQUIRES_FEATURE.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| guild_id | snowflake | The ID of the guild |
JSON body
Section titled “JSON body”| Field | Type | Description |
|---|---|---|
| code?1 | ?string | Custom invite code to claim, or null to remove the current code |
1 Fluxer lowercases the value, turns each whitespace run into one hyphen, and collapses repeated hyphens. The result must match ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$ and be 2 to 32 characters
A result that fails the pattern is rejected with the field code VANITY_URL_INVALID_CHARACTERS, and one outside the length bound with VANITY_URL_CODE_LENGTH_INVALID. A code containing the term fluxer is rejected with the field code VANITY_URL_CODE_CANNOT_CONTAIN_FLUXER. Sending the code the guild already holds returns that code unchanged, after the feature and reserved term checks and before the uniqueness check. A code that any existing invite already holds is otherwise rejected with the field code VANITY_URL_CODE_ALREADY_TAKEN.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | custom invite URL selection object | Code was claimed, removed, or already matched |
| 4001 | error response | Code, reserved term policy, feature requirement, or global uniqueness check rejects the request |
| 4001 | error response | Caller cannot exercise MANAGE_GUILD |
| 4032 | error response | Guild is unavailable, the code is blocked, or MANAGE_GUILD is absent |
| 404 | error response | Guild does not exist and the request returns UNKNOWN_GUILD |
1 The error code is TWO_FACTOR_REQUIRED for a caller who holds MANAGE_GUILD but cannot exercise it, and INVALID_FORM_BODY otherwise
2 The error code is MISSING_ACCESS for an unavailable guild, CONTENT_BLOCKED for a blocked code, and MISSING_PERMISSIONS for a non-member or a caller lacking MANAGE_GUILD
Side effects
Section titled “Side effects”Supplying the current code, or removing a code when the guild has none, changes nothing, records no audit entry, and emits no Dispatch. Any other request deletes the invite backing the previous code. Where a code was supplied, it claims the new one. It records a GUILD_UPDATE audit entry with the previous and new code, emits Guild Update to every session that can see the guild, and emits Guild Audit Log Entry Create to sessions that can read the audit log.
Rate limit
Section titled “Rate limit”10 requests per minute for each authenticated user and guild, on the guild:vanity_url:patch::guild_id bucket.