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. A non-member receives 403 MISSING_PERMISSIONS. A guild that exists in storage but that the Gateway reports as not found returns 403 ACCESS_DENIED.

An unavailable guild can still appear in List current user guilds. Members can still leave or delete their own messages.

Submitted names and other text must pass the instance’s content policy. Blocked content returns 403 CONTENT_BLOCKED.

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

Field	Type	Description
id	snowflake	The ID of the guild
name	string	The name of the guild (1-100 characters)
icon¹	?string	Guild icon hash
banner²	?string	Guild banner hash
banner_width³	?integer	Banner width in pixels
banner_height³	?integer	Banner height in pixels
splash⁴	?string	Invite splash hash
splash_width³	?integer	Invite splash width in pixels
splash_height³	?integer	Invite splash height in pixels
splash_card_alignment	integer	Splash card alignment
embed_splash⁴	?string	Embedded invite splash hash
embed_splash_width³	?integer	Embedded invite splash width in pixels
embed_splash_height³	?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_id⁵	?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)
features⁶	array[string]	Guild features
verification_level	integer	Verification level
mfa_level	integer	MFA level
nsfw_level⁷	integer	NSFW level
nsfw	boolean	Whether the guild is marked as adult content
content_warning_level	integer	Guild content warning level
content_warning_text⁸	?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_operations⁹	integer	Disabled guild operations
message_history_cutoff¹⁰	?ISO8601 timestamp	Earliest message visible to a member without `READ_MESSAGE_HISTORY`
permissions?¹¹	decimal string	Caller permissions in the guild
roles?¹²	array[guild role object]	Guild roles
emojis?¹²	array[guild emoji object]	Guild emojis
stickers?¹²	array[guild sticker object]	Guild stickers
channels?¹³	array[channel object]	Guild channels the caller can view
member_count?¹⁴	integer	Member count held by the main Gateway
online_count?¹⁴	integer	Online presence count held by the main Gateway
approximate_member_count?¹⁵	integer	Approximate member count
approximate_presence_count?¹⁵	integer	Approximate online presence count

¹ An animated icon hash has the a_ prefix, and that prefix is removed from the returned value while the guild lacks ANIMATED_ICON

² 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

³ The dimension is null whenever its own asset hash field is null

⁴ The field is null whenever the guild lacks INVITE_SPLASH

⁵ No operation on this page assigns the rules channel

⁶ The set has each feature at most once, and its order is not stable

⁷ The value is derived from nsfw, so it is 3 when nsfw is true and 0 otherwise

⁸ A null value means the client renders the localised default warning text for the guild

⁹ Written only through the Admin API

¹⁰ 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

¹¹ 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

¹² Only Get guild populates this field

¹³ Only Get guild populates this field, and the array is filtered to the channels the caller can currently view

¹⁴ Only Get guild populates these fields

¹⁵ Only List current user guilds populates these fields, and only when with_counts is true. A guild for which the Gateway holds no cached counts reports 0 for both

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

A partial guild object is the smaller shape that appears inside invite payloads. It has identity and display fields only, and the feature-gated asset rules of the complete guild object apply to it unchanged.

Structure

Field	Type	Description
id	snowflake	The ID of the guild
name	string	The name of the guild
icon¹	?string	Guild icon hash
banner²	?string	Guild banner hash
banner_width³	?integer	Banner width in pixels
banner_height³	?integer	Banner height in pixels
splash⁴	?string	Invite splash hash
splash_width³	?integer	Invite splash width in pixels
splash_height³	?integer	Invite splash height in pixels
splash_card_alignment	integer	Splash card alignment
embed_splash⁴	?string	Embedded invite splash hash
embed_splash_width³	?integer	Embedded invite splash width in pixels
embed_splash_height³	?integer	Embedded invite splash height in pixels
features⁵	array[string]	Guild features

¹ An animated icon hash has the a_ prefix, and that prefix is removed from the returned value while the guild lacks ANIMATED_ICON

² 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

³ The dimension is null whenever its own asset hash field is null

⁴ The field is null whenever the guild lacks INVITE_SPLASH

⁵ The set has each feature at most once, and vanity_url_code is never part of this representation

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

A creation template describes the roles and channels that Create guild creates. FiveCord 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

Field	Type	Description
name¹	string	Template name
description?¹	?string	Template description
verification_level?²	integer	Verification level, defaulting to 0
default_message_notifications?²	integer	Default message notification level, defaulting to 0
explicit_content_filter?²	integer	Guild explicit content filter level, defaulting to 0
system_channel_id?³	?decimal string \| integer	Template-local ID of the text channel that becomes the system channel
afk_timeout?²	integer	AFK timeout in seconds, clamped to 60-3600 and defaulting to 300
system_channel_flags?⁴	integer	System channel flags, defaulting to 0
roles⁵	array[guild template role object]	Template roles (max 250)
channels⁶	array[guild template channel object]	Template channels (max 500)

¹ The field is read and discarded. The new guild takes its name from the name of the Create guild body

² 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

³ 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

⁴ Every bit outside the registry is discarded

⁵ 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

⁶ A template with more than 500 channels is rejected with 400 GUILD_TEMPLATE_INVALID

Guild template role object

Structure

Field	Type	Description
id¹	decimal string \| integer	Template-local role ID
name?²	?string	Role name, defaulting to the empty string
permissions?³	decimal string \| integer	Legacy role permission bitfield
permissions_new?³	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?⁴	?string	Role Unicode emoji

¹ A duplicate identifier rejects creation with 400 GUILD_TEMPLATE_INVALID

² 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

³ permissions_new takes precedence over permissions, the value is masked to the permission bits FiveCord 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

⁴ The value is stored on the created role. The everyone role is always created with no Unicode emoji

Guild template channel object

Structure

Field	Type	Description
id¹	decimal string \| integer	Template-local channel ID
type²	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?³	?decimal string \| integer	Template-local parent category ID
bitrate?⁴	?integer	Voice bitrate, defaulting to 64000 for a voice channel and capped at 96000
user_limit?⁴	?integer	Voice occupancy limit, defaulting to 0 for a voice channel
voice_connection_limit?⁴	?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?⁵	array[guild template role permission overwrite object]	Role permission overwrites

¹ A duplicate identifier in the same template rejects creation with 400 GUILD_TEMPLATE_INVALID

² The value 0 creates a text channel, 2 a voice channel, and 4 a category. The value 5, the announcement channel type of another platform, creates a text channel. The value 13, the stage channel type of another platform, creates a voice channel. FiveCord skips every other value, so the channel is not created

³ 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

⁴ These voice fields are stored only on a voice channel and are null on every other channel type

⁵ 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. FiveCord skips every other entry, and a channel whose entries are all skipped is created with no overwrites

Guild template role permission overwrite object

Structure

Field	Type	Description
id	decimal string \| integer	Template-local role ID
type¹	integer \| string	Overwrite type
allow²	decimal string \| integer	Allowed permission bitfield
deny²	decimal string \| integer	Denied permission bitfield

¹ 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

² The value is masked to the permission bits FiveCord defines, and a value that is not a valid integer rejects creation with 400 GUILD_TEMPLATE_INVALID

Verification levels

A verification level gates member participation. FiveCord evaluates it when a member sends a message in the guild.

Value	Name	Description
0	NONE	No verification requirement
1	LOW¹	The account is claimed and its email address verified
2	MEDIUM	The LOW requirement, and the account is at least 5 minutes old
3	HIGH²	The MEDIUM requirement, and the membership is at least 10 minutes old
4	VERY_HIGH³	The account has a verified phone number

¹ 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

² The membership age requirement is skipped when the join timestamp cannot be read, so the level behaves as MEDIUM

³ 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

Value	Name	Description
0	NONE	MFA is not required for moderation actions
1	ELEVATED¹	MFA is required for moderation actions

¹ 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 non-owner caller uses the elevated permissions only with an enrolled authenticator. A bot inherits the enrolment state of its application owner. An operation that asserts an elevated permission the caller holds but cannot use returns 400 TWO_FACTOR_REQUIRED after confirming the permission itself.

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

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

Value	Name	Description
0	ALL_MESSAGES	Notify for all messages by default
1	ONLY_MENTIONS	Notify only for mentions by default

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. FiveCord derives the level from the guild’s nsfw field and never writes it directly.

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

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

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

Each value in the guild’s features array is a capability or availability flag.

Value	Description
ANIMATED_ICON	Guild can use an animated icon
ANIMATED_BANNER	Guild can use an animated banner
AUDIO_BITRATE_128_KBPS⁶	Voice channel bitrate ceiling is raised to 128000
AUDIO_BITRATE_256_KBPS⁶	Voice channel bitrate ceiling is raised to 256000
AUDIO_BITRATE_384_KBPS⁶	Voice channel bitrate ceiling is raised to 384000
BANNER	Guild can use a banner
CLONE_EMOJI_DISABLED⁷	Deprecated. Emoji cloning now needs CLONE_EMOJI_ENABLED
CLONE_EMOJI_ENABLED¹	Guild permits another guild to clone its emojis
CLONE_STICKER_DISABLED⁷	Deprecated. Sticker cloning now needs CLONE_STICKER_ENABLED
CLONE_STICKER_ENABLED¹	Guild permits another guild to clone its stickers
DETACHED_BANNER¹	Guild banner is independent from its splash
INVITE_SPLASH	Guild can use invite splash assets
INVITES_DISABLED¹	Guild invite use is disabled
RAID_DETECTED	Raid detection is active and invites are restricted
TEXT_CHANNEL_FLEXIBLE_NAMES¹	Text channel names keep uppercase letters, spaces, and punctuation
HIDE_OWNER_CROWN¹	Guild owner crown is hidden
MORE_EMOJI²	Legacy increased emoji slot allowance
MORE_STICKERS²	Legacy increased sticker slot allowance
UNLIMITED_EMOJI³	Guild emoji slots are effectively unlimited
UNLIMITED_STICKERS³	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 can use voice regions that are restricted to VIP guilds
VOICE_E2EE	Guild voice channels support end-to-end encryption
UNAVAILABLE_FOR_EVERYONE⁴	Guild is unavailable to every account
UNAVAILABLE_FOR_EVERYONE_BUT_STAFF⁴	Guild is unavailable to every account without the instance staff flag
UNAVAILABLE_HIDDEN	While the guild is unavailable, the Gateway sends its unavailable guild entry with `unavailable_hidden: true`
VISIONARY	Guild has visionary status
LARGE_GUILD_OVERRIDE²	Guild is marked as a large guild
VERY_LARGE_GUILD⁵	Guild member capacity is raised

¹ 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

² 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 them

³ Emoji and sticker creation use a fixed slot ceiling of 999999 and ignore the instance limit configuration

⁴ Guild and channel routes return 403 MISSING_ACCESS. UNAVAILABLE_FOR_EVERYONE includes the guild owner. UNAVAILABLE_FOR_EVERYONE_BUT_STAFF exempts accounts with the instance staff flag

⁵ The feature raises the default max_guild_members limit from 1000000 to 10000000 before the ordered limit configuration is checked, so the raised ceiling applies even when no configured rule names the feature

⁶ A guild holding none of the three caps a voice channel bitrate at 96000. The highest feature the guild holds wins, and a write above the cap is stored at the cap rather than rejected. A guild that loses the feature keeps the stored value, and the next write to bitrate lowers it to the cap

⁷ The feature is deprecated and changes no behaviour. FiveCord still returns it for a guild that already holds it, and Modify guild can neither add nor remove it

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

Field	Type	Description
code	?string	Current custom invite code
uses¹	integer	Use count of the invite backing the current code

¹ The value is 0 when the guild holds no code and when the backing invite can no longer be resolved

Example

{
  "code": "workshop",
  "uses": 128
}

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

Field	Type	Description
code	?string	Custom invite code held by the guild after the request (2-32 characters)

Sudo verification fields

These fields prove sudo mode when an operation requires it. A caller can also supply an existing proof through the X-FiveCord-Sudo-Mode-JWT request header.

Structure

Field	Type	Description
password?¹	string	Current account password
mfa_method?²	string	MFA method, either `totp` or `webauthn`
mfa_code?	string	Authenticator code or unconsumed backup 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

¹ The password is accepted only while the account holds neither a TOTP secret nor a registered WebAuthn credential, and it returns the field code INVALID_PASSWORD when it does not match

² The MFA proof is accepted only while the account holds a TOTP secret or a registered WebAuthn credential, and it returns the field code INVALID_MFA_CODE on any failure

A bot credential satisfies sudo mode without any proof, and so does an account with no password, no TOTP secret, and no registered WebAuthn credential. 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, webauthn, and backup_codes are available.

FiveCord issues a newly generated proof in the X-FiveCord-Sudo-Mode-JWT header of the success response, and only for an account holding a TOTP secret or a registered WebAuthn credential. A proof supplied on the request is echoed back in that same header.

Create guild

POST/v1/guilds

Creates 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

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 single_community_enabled is true in the instance policy, every caller is rejected with 400 SINGLE_COMMUNITY_CANNOT_CREATE_GUILDS.

JSON body

Field	Type	Description
name¹	string	Guild name (1-100 characters)
icon?²	?base64 string	Guild icon
empty_features?³	boolean	Whether to create the guild with no features (default false)
template?	guild creation template object	Roles and channels to create for the new guild

¹ FiveCord trims the value before it measures the length bound

² The field accepts raw base64, or a data URL whose payload is everything after the first comma

³ When false the guild is created holding ANIMATED_ICON, ANIMATED_BANNER, BANNER, and INVITE_SPLASH

A name outside 1 to 100 characters after normalisation returns STRING_LENGTH_INVALID. A blocked name 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

Status	Body	Condition
200	guild object	Guild was created
400¹	error response	Body, image, template, bot or unclaimed credential, configured guild limit, or single community policy rejects creation
403²	error response	Email address is unverified, or the name is blocked

¹ 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

² 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

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. FiveCord 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

10 requests per minute for each authenticated user, on the guild:create bucket.

List current user guilds

GET/v1/users/@me/guilds

Bot guilds

Returns 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

Field	Type	Description
before?¹	snowflake	Return guilds with a lower ID than this guild ID
after?¹	snowflake	Return guilds with a higher ID than this guild ID
limit?	integer	Maximum number returned (1-200, default 200)
with_counts?²	boolean	Include approximate member and presence counts (default false)

¹ 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

² A guild whose counts cannot be fetched is returned without them

The page excludes deleted guilds but includes guilds marked UNAVAILABLE_FOR_EVERYONE.

A page within that ceiling can still omit permissions from an individual guild the lookup could not resolve.

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

40 requests per 10 seconds for each authenticated user, on the guild:list bucket.

Get guild

GET/v1/guilds/{guild_id}

Bot guilds

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

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response

Status	Body	Condition
200	guild object	Guild was returned
403¹	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`

¹ 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 guild exists in storage but the Gateway reports it as not found

Rate limit

100 requests per 10 seconds for each authenticated user and guild, on the guild:read::guild_id bucket.

Modify guild

PATCH/v1/guilds/{guild_id}

Bot Audit reason MFA

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 non-owner caller also needs an enrolled authenticator, and receives 400 TWO_FACTOR_REQUIRED without one.

Changing mfa_level to a different value also 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

Field	Type	Description
guild_id	snowflake	The ID of the guild

Request headers

Field	Type	Description
X-FiveCord-Sudo-Mode-JWT?	string	Existing sudo mode proof, read when the MFA level changes

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?¹	string	Guild name (1-100 characters)
icon?²	?base64 string	Guild icon, or null to clear it
system_channel_id?³	?snowflake	System channel ID, or null to clear it
system_channel_flags?⁴	integer	System channel flags
afk_channel_id?⁵	?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?⁶	integer	Verification level
mfa_level?⁷	integer	MFA level
nsfw_level?⁸	integer	Legacy NSFW level, which is translated into `nsfw` and the content warning level
nsfw?⁹	boolean	Whether the guild is marked as adult content
content_warning_level?¹⁰	integer	Guild content warning level
content_warning_text?¹¹	?string	Content warning text (max 200 characters), or null for the localised default
explicit_content_filter?	integer	Guild explicit content filter level
banner?¹²	?base64 string	Guild banner, or null to clear it
splash?¹³	?base64 string	Static invite splash, or null to clear it
embed_splash?¹³	?base64 string	Static embedded invite splash, or null to clear it
splash_card_alignment?	integer	Splash card alignment
features?¹⁴	array[string]	Complete desired guild feature set (max 100 entries)
message_history_cutoff?¹⁵	?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

¹ Normalised and trimmed before its length is measured. A blocked name returns 403 CONTENT_BLOCKED

² 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

³ 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

⁴ Every bit outside the registry is discarded

⁵ 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

⁶ A guild with DISCOVERABLE cannot be lowered below LOW and is rejected with the field code DISCOVERABLE_GUILD_VERIFICATION_LEVEL_TOO_LOW

⁷ 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

⁸ 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 content warning level is INHERIT

⁹ 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

¹⁰ Any value other than 1 is stored as 0

¹¹ The value is trimmed, and a value that is empty after trimming is stored as null

¹² A non-null value requires BANNER, and an animated image also requires ANIMATED_BANNER, otherwise the request is rejected with the field codes GUILD_BANNER_REQUIRES_FEATURE or ANIMATED_GUILD_BANNER_REQUIRES_FEATURE

¹³ 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

¹⁴ 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_ENABLED, CLONE_STICKER_ENABLED, and HIDE_OWNER_CROWN

¹⁵ 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

Status	Body	Condition
200	guild object	Guild was modified, or the supplied values matched current state
400¹	error response	Body, image, feature set, channel reference, timestamp, or sudo proof is invalid
400¹	error response	Caller cannot use `MANAGE_GUILD`
403²	error response	Guild is unavailable, the name is blocked, `MANAGE_GUILD` or ownership is absent, or sudo mode is required
404³	error response	Guild does not exist

¹ The error code is TWO_FACTOR_REQUIRED for a caller who holds MANAGE_GUILD but cannot use it, and INVALID_FORM_BODY otherwise

² 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

³ The error code is UNKNOWN_GUILD

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.

A request that changes the stored value of at least one body field records a GUILD_UPDATE audit entry with the previous and new values. That entry 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 changes when FiveCord trims it, lowercases it, replaces each whitespace run with a hyphen, and removes disallowed punctuation. When at least one channel is renamed, the removal emits one Channel Update Bulk Dispatch with every channel in the guild.

Replacing an image removes the previous asset. A failed replacement leaves the previous image unchanged.

Rate limit

20 requests per 10 seconds for each authenticated user and guild, on the guild:update::guild_id bucket.

Delete guild

POST/v1/guilds/{guild_id}/delete

MFA

Permanently 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.

FiveCord refuses a non-owner with 403 MISSING_PERMISSIONS. A bot can never own a guild, so a bot credential never satisfies the requirement.

While single_community_enabled is true in the instance policy, the guild named by single_community_guild_id cannot be deleted and returns 400 SINGLE_COMMUNITY_CANNOT_DELETE.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Request headers

Field	Type	Description
X-FiveCord-Sudo-Mode-JWT?	string	Existing sudo mode proof

JSON body

The body is the optional sudo verification fields. A request that already has a valid proof can omit it.

Response

Status	Body	Condition
204	empty	Guild was deleted
400¹	error response	Body, sudo proof, or single community policy rejects the request
403²	error response	Guild is unavailable, the caller is not the owner, or sudo mode is required
404³	error response	Guild does not exist

¹ The error code is SINGLE_COMMUNITY_CANNOT_DELETE while the policy protects this guild, and INVALID_FORM_BODY otherwise

² 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

³ The error code is UNKNOWN_GUILD

Side effects

Every member receives Guild Delete. FiveCord deletes every member’s user guild settings for the guild. Non-bot members also receive User Settings Update with the guild removed from their folder layout.

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

10 requests per minute for each authenticated user and guild, on the guild:delete::guild_id bucket.

Leave guild

DELETE/v1/users/@me/guilds/{guild_id}

Bot

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. While single_community_enabled is true in the instance policy, the guild named by single_community_guild_id cannot be left and returns 400 SINGLE_COMMUNITY_CANNOT_LEAVE. Setting delete_messages requires sudo mode, which a bot credential satisfies implicitly.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Query parameters

Field	Type	Description
delete_messages?¹	boolean	Delete every message the caller authored in the guild before leaving (default false)

¹ The deletion runs inside this request and completes before the membership is removed. The response is sent only after every matching message is gone

With delete_messages, a non-member of an existing guild receives 403 MISSING_PERMISSIONS rather than 404 UNKNOWN_MEMBER.

Request headers

Field	Type	Description
X-FiveCord-Sudo-Mode-JWT?	string	Existing sudo mode proof, read only when `delete_messages` is true

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

Status	Body	Condition
204	empty	Membership was removed
400¹	error response	Query, body, sudo proof, guild ownership, or single community policy rejects the request
403²	error response	Sudo mode is required, or the caller is not a member while `delete_messages` is true
404³	error response	Caller holds no membership in the guild

¹ 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

² 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

³ The error code is UNKNOWN_MEMBER, and UNKNOWN_GUILD when delete_messages is true and the guild does not exist

Side effects

The account leaves the guild. Non-bot accounts receive User Settings Update with the guild removed from their folder layout.

Remaining guild sessions receive Guild Member Remove and the leaving account’s sessions receive Guild Delete.

Guild read states and settings are unchanged, but the guild profile and roles are lost. Rejoining within one year resumes any unexpired communication timeout. Leaving records no audit entry, and X-Audit-Log-Reason has no effect.

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

POST/v1/users/@me/guilds/{guild_id}/messages/bulk-delete-mine

Bot MFA

Deletes 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

Field	Type	Description
guild_id	snowflake	The ID of the guild

Request headers

Field	Type	Description
X-FiveCord-Sudo-Mode-JWT?	string	Existing sudo mode proof

JSON body

The body is the optional sudo verification fields.

Response

Status	Body	Condition
202	empty	Messages were deleted
400	error response	Body or sudo proof is invalid
403¹	error response	Caller is not a member, or sudo mode is required
404²	error response	Guild does not exist

¹ The error code is MISSING_PERMISSIONS for a caller who is not a member and SUDO_MODE_REQUIRED when sudo mode is unproven

² The error code is UNKNOWN_GUILD

Side effects

The caller’s messages and attachments are permanently deleted. Affected channels receive Message Delete Bulk events with up to 100 message IDs each. No audit entry is recorded.

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

GET/v1/guilds/{guild_id}/vanity-url

Bot

Returns 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 non-owner caller also needs an enrolled authenticator, and receives 400 TWO_FACTOR_REQUIRED without one.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

Response

Status	Body	Condition
200	custom invite URL object	Custom invite URL state was returned
400¹	error response	Caller cannot use `MANAGE_GUILD`
403²	error response	Guild is unavailable, or `MANAGE_GUILD` is absent
404	error response	Guild does not exist and the request returns `UNKNOWN_GUILD`

¹ The error code is TWO_FACTOR_REQUIRED

² 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

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

PATCH/v1/guilds/{guild_id}/vanity-url

Bot Audit reason MFA

Sets 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 non-owner caller also needs an enrolled authenticator, and receives 400 TWO_FACTOR_REQUIRED without one.

A non-null code also requires the VANITY_URL guild feature and is otherwise rejected with the field code VANITY_URL_REQUIRES_FEATURE.

Path parameters

Field	Type	Description
guild_id	snowflake	The ID of the guild

JSON body

Field	Type	Description
code?¹	?string	Custom invite code to claim, or null to remove the current code

¹ FiveCord 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 returns VANITY_URL_INVALID_CHARACTERS, and one outside the length bound returns VANITY_URL_CODE_LENGTH_INVALID. A code containing fluxer returns VANITY_URL_CODE_CANNOT_CONTAIN_FLUXER. An unchanged valid code succeeds. A code claimed by another invite returns VANITY_URL_CODE_ALREADY_TAKEN.

Response

Status	Body	Condition
200	custom invite URL selection object	Code was claimed, removed, or already matched
400¹	error response	Code, reserved term policy, feature requirement, or global uniqueness check rejects the request
400¹	error response	Caller cannot use `MANAGE_GUILD`
403²	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`

¹ The error code is TWO_FACTOR_REQUIRED for a caller who holds MANAGE_GUILD but cannot use it, and INVALID_FORM_BODY otherwise

² 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

An unchanged code has no side effects. A change replaces or removes the previous invite, records a GUILD_UPDATE audit entry and emits Guild Update and Guild Audit Log Entry Create.

Rate limit

10 requests per minute for each authenticated user and guild, on the guild:vanity_url:patch::guild_id bucket.