Guild

Reference for Discord guild (server) objects, features, and management endpoints.

Guilds in Discord represent an isolated collection of users and channels, and are often referred to as “servers” in the UI.

Guild object

Fields specific to the GUILD_CREATE event are listed in the Gateway Events documentation.

Guild structure

id · snowflake · required

Guild id

name · string · required

Guild name (2-100 characters, excluding trailing and leading whitespace)

icon · ?string · required

Icon hash

icon_hash · ?string

Icon hash, returned when in the template object

splash · ?string · required

Splash hash

discovery_splash · ?string · required

Discovery splash hash; only present for guilds with the DISCOVERABLE feature

owner · boolean

True if the user is the owner of the guild. Only sent when using the Get Current User Guilds endpoint.

owner_id · snowflake · required

ID of owner

permissions · string

Total permissions for the user in the guild (excludes overwrites and implicit permissions). Only sent when using the Get Current User Guilds endpoint.

afk_channel_id · ?snowflake · required

ID of afk channel

afk_timeout · integer · required

AFK timeout in seconds

widget_enabled · boolean

True if the server widget is enabled

widget_channel_id · ?snowflake

The channel id that the widget will generate an invite to, or null if set to no invite

verification_level · integer · required

Verification level required for the guild

default_message_notifications · integer · required

Default message notifications level

explicit_content_filter · integer · required

Explicit content filter level

roles · array of role objects · required

Roles in the guild

emojis · array of emoji objects · required

Custom guild emojis

features · array of guild feature strings · required

Enabled guild features

mfa_level · integer · required

Required MFA level for the guild

application_id · ?snowflake · required

Application id of the guild creator if it is bot-created

system_channel_id · ?snowflake · required

The id of the channel where guild notices such as welcome messages and boost events are posted

system_channel_flags · integer · required

System channel flags

rules_channel_id · ?snowflake · required

The id of the channel where Community guilds can display rules and/or guidelines

max_presences · ?integer

The maximum number of presences for the guild (null is always returned, apart from the largest of guilds)

max_members · integer

The maximum number of members for the guild

vanity_url_code · ?string · required

The vanity url code for the guild

description · ?string · required

The description of a guild

banner · ?string · required

Banner hash

premium_tier · integer · required

Premium tier (Server Boost level)

premium_subscription_count · integer

The number of boosts this guild currently has

preferred_locale · string · required

The preferred locale of a Community guild; used in server discovery and notices from Discord; defaults to “en-US”

public_updates_channel_id · ?snowflake · required

The id of the channel where admins and moderators of Community guilds receive notices from Discord

max_video_channel_users · integer

The maximum amount of users in a video channel

max_stage_video_channel_users · integer

The maximum amount of users in a stage video channel

approximate_member_count · integer

Approximate number of members in this guild. Returned when with_counts is true.

approximate_presence_count · integer

Approximate number of non-offline members in this guild. Returned when with_counts is true.

welcome_screen · welcome screen object

The welcome screen of a Community guild, shown to new members

nsfw_level · integer · required

Guild age-restriction level

stickers · array of sticker objects

Custom guild stickers

premium_progress_bar_enabled · boolean · required

Whether the guild has the boost progress bar enabled

safety_alerts_channel_id · ?snowflake · required

The id of the channel where admins and moderators of Community guilds receive safety alerts from Discord

incidents_data · ?incidents data object · required

The incidents data for this guild

Default message notification level

Key	Value	Description
ALL_MESSAGES	0	Members will receive notifications for all messages by default
ONLY_MENTIONS	1	Members will receive notifications only for messages that @mention them by default

Explicit content filter level

Level	Integer	Description
DISABLED	0	Media content will not be scanned
MEMBERS_WITHOUT_ROLES	1	Media content sent by members without roles will be scanned
ALL_MEMBERS	2	Media content sent by all members will be scanned

MFA level

Level	Integer	Description
NONE	0	Guild has no MFA/2FA requirement for moderation actions
ELEVATED	1	Guild has a 2FA requirement for moderation actions

Verification level

Level	Integer	Description
NONE	0	Unrestricted
LOW	1	Must have verified email on account
MEDIUM	2	Must be registered on Discord for longer than 5 minutes
HIGH	3	Must be a member of the server for longer than 10 minutes
VERY_HIGH	4	Must have a verified phone number

Guild NSFW level

Level	Value
DEFAULT	0
EXPLICIT	1
SAFE	2
AGE_RESTRICTED	3

Premium tier

Level	Integer	Description
NONE	0	Guild has not unlocked any Server Boost perks
TIER_1	1	Guild has unlocked Server Boost level 1 perks
TIER_2	2	Guild has unlocked Server Boost level 2 perks
TIER_3	3	Guild has unlocked Server Boost level 3 perks

System channel flags

Flag	Value	Description
SUPPRESS_JOIN_NOTIFICATIONS	1 << 0	Suppress member join notifications
SUPPRESS_PREMIUM_SUBSCRIPTIONS	1 << 1	Suppress server boost notifications
SUPPRESS_GUILD_REMINDER_NOTIFICATIONS	1 << 2	Suppress server setup tips
SUPPRESS_JOIN_NOTIFICATION_REPLIES	1 << 3	Hide member join sticker reply buttons
SUPPRESS_ROLE_SUBSCRIPTION_PURCHASE_NOTIFICATIONS	1 << 4	Suppress role subscription purchase and renewal notifications
SUPPRESS_ROLE_SUBSCRIPTION_PURCHASE_NOTIFICATION_REPLIES	1 << 5	Hide role subscription sticker reply buttons

Guild features

Feature	Description
ANIMATED_BANNER	Guild has access to set an animated guild banner image
ANIMATED_ICON	Guild has access to set an animated guild icon
APPLICATION_COMMAND_PERMISSIONS_V2	Guild is using the old permissions configuration behavior
AUTO_MODERATION	Guild has set up auto moderation rules
BANNER	Guild has access to set a guild banner image
COMMUNITY	Guild can enable welcome screen, Membership Screening, and stage channels
CREATOR_MONETIZABLE_PROVISIONAL	Guild has enabled monetization
CREATOR_STORE_PAGE	Guild has enabled the role subscription promo page
DEVELOPER_SUPPORT_SERVER	Guild has been set as a support server on the App Directory
DISCOVERABLE	Guild is able to be discovered in the directory
FEATURABLE	Guild is able to be featured in the directory
INVITES_DISABLED	Guild has paused invites, preventing new users from joining
INVITE_SPLASH	Guild has access to set an invite splash background
MEMBER_VERIFICATION_GATE_ENABLED	Guild has enabled Membership Screening
MORE_SOUNDBOARD	Guild has increased custom soundboard sound slots
MORE_STICKERS	Guild has increased custom sticker slots
NEWS	Guild has access to create announcement channels
PARTNERED	Guild is partnered
PREVIEW_ENABLED	Guild can be previewed before joining via Membership Screening
RAID_ALERTS_DISABLED	Guild has disabled alerts for join raids in the safety alerts channel
ROLE_ICONS	Guild is able to set role icons
ROLE_SUBSCRIPTIONS_AVAILABLE_FOR_PURCHASE	Guild has role subscriptions that can be purchased
ROLE_SUBSCRIPTIONS_ENABLED	Guild has enabled role subscriptions
SOUNDBOARD	Guild has created soundboard sounds
TICKETED_EVENTS_ENABLED	Guild has enabled ticketed events
VANITY_URL	Guild has access to set a vanity URL
VERIFIED	Guild is verified
VIP_REGIONS	Guild has access to set 384kbps bitrate in voice
WELCOME_SCREEN_ENABLED	Guild has enabled the welcome screen
GUESTS_ENABLED	Guild has access to guest invites
GUILD_TAGS	Guild has access to set guild tags
ENHANCED_ROLE_COLORS	Guild is able to set gradient colors to roles

Mutable guild features

Feature	Required permissions	Effects
COMMUNITY	Administrator	Enables Community Features in the guild
DISCOVERABLE	Administrator*	Enables discovery in the guild, making it publicly listed
INVITES_DISABLED	Manage Guild	Pauses all invites/access to the server
RAID_ALERTS_DISABLED	Manage Guild	Disables alerts for join raids

* Server must also be passing all discovery requirements.

Example guild

{
  "id": "197038439483310086",
  "name": "Discord Testers",
  "icon": "f64c482b807da4f539cff778d174971c",
  "description": "The official place to report Discord Bugs!",
  "splash": null,
  "discovery_splash": null,
  "features": ["ANIMATED_ICON", "VERIFIED", "NEWS", "VANITY_URL", "DISCOVERABLE"],
  "emojis": [],
  "banner": "9b6439a7de04f1d26af92f84ac9e1e4a",
  "owner_id": "73193882359173120",
  "application_id": null,
  "region": null,
  "afk_channel_id": null,
  "afk_timeout": 300,
  "system_channel_id": null,
  "widget_enabled": true,
  "widget_channel_id": null,
  "verification_level": 3,
  "roles": [],
  "default_message_notifications": 1,
  "mfa_level": 1,
  "explicit_content_filter": 2,
  "vanity_url_code": "discord-testers",
  "premium_tier": 3,
  "premium_subscription_count": 33,
  "system_channel_flags": 0,
  "preferred_locale": "en-US",
  "rules_channel_id": "441688182833020939",
  "public_updates_channel_id": "281283303326089216",
  "safety_alerts_channel_id": "281283303326089216"
}

Guild member object

Guild member structure

user · user object

The user this guild member represents. Not included in the member object attached to MESSAGE_CREATE and MESSAGE_UPDATE gateway events.

nick · ?string

This user’s guild nickname

avatar · ?string

The member’s guild avatar hash

banner · ?string

The member’s guild banner hash

roles · array of snowflakes · required

Array of role object ids

joined_at · ?ISO8601 timestamp · required

When the user joined the guild

premium_since · ?ISO8601 timestamp

When the user started boosting the guild

deaf · boolean · required

Whether the user is deafened in voice channels

mute · boolean · required

Whether the user is muted in voice channels

flags · integer · required

Guild member flags represented as a bit set, defaults to 0

pending · boolean

Whether the user has not yet passed the guild’s Membership Screening requirements

permissions · string

Total permissions of the member in the channel, including overwrites, returned when in the interaction object

communication_disabled_until · ?ISO8601 timestamp

When the user’s timeout will expire and the user will be able to communicate in the guild again, null or a time in the past if the user is not timed out

avatar_decoration_data · ?avatar decoration data object

Data for the member’s guild avatar decoration

Guild member flags

Flag	Value	Description	Editable
DID_REJOIN	1 << 0	Member has left and rejoined the guild	false
COMPLETED_ONBOARDING	1 << 1	Member has completed onboarding	false
BYPASSES_VERIFICATION	1 << 2	Member is exempt from guild verification requirements	true
STARTED_ONBOARDING	1 << 3	Member has started onboarding	false
IS_GUEST	1 << 4	Member is a guest and can only access the voice channel they were invited to	false
STARTED_HOME_ACTIONS	1 << 5	Member has started Server Guide new member actions	false
COMPLETED_HOME_ACTIONS	1 << 6	Member has completed Server Guide new member actions	false
AUTOMOD_QUARANTINED_USERNAME	1 << 7	Member’s username, display name, or nickname is blocked by AutoMod	false
DM_SETTINGS_UPSELL_ACKNOWLEDGED	1 << 9	Member has dismissed the DM settings upsell	false
AUTOMOD_QUARANTINED_GUILD_TAG	1 << 10	Member’s guild tag is blocked by AutoMod	false

Ban object

reason · ?string · required

The reason for the ban

user · user object · required

The banned user

Welcome screen object

description · ?string · required

The server description shown in the welcome screen

welcome_channels · array of welcome screen channel objects · required

The channels shown in the welcome screen, up to 5

Welcome screen channel structure

channel_id · snowflake · required

The channel’s id

description · string · required

The description shown for the channel

emoji_id · ?snowflake · required

The emoji id, if the emoji is custom

emoji_name · ?string · required

The emoji name if custom, the unicode character if standard, or null if no emoji is set

Incidents data object

invites_disabled_until · ?ISO8601 timestamp · required

When invites get enabled again

dms_disabled_until · ?ISO8601 timestamp · required

When direct messages get enabled again

dm_spam_detected_at · ?ISO8601 timestamp

When the DM spam was detected

raid_detected_at · ?ISO8601 timestamp

When the raid was detected

---

Get guild

GET /guilds/{guild.id}

Returns the guild object for the given id. If with_counts is set to true, this endpoint will also return approximate_member_count and approximate_presence_count for the guild.

Query string params

with_counts · boolean · default: "false"

When true, will return approximate member and presence counts for the guild

Get guild preview

GET /guilds/{guild.id}/preview

Returns the guild preview object for the given id. If the user is not in the guild, then the guild must be discoverable.

Modify guild

PATCH /guilds/{guild.id}

Modify a guild’s settings. Requires the MANAGE_GUILD permission. Returns the updated guild object on success.

All parameters to this endpoint are optional.

This endpoint supports the X-Audit-Log-Reason header.

Attempting to add or remove the COMMUNITY guild feature requires the ADMINISTRATOR permission.

JSON params

name · string

Guild name

verification_level · ?integer

Verification level

default_message_notifications · ?integer

Default message notification level

explicit_content_filter · ?integer

Explicit content filter level

afk_channel_id · ?snowflake

ID for afk channel

afk_timeout · integer

AFK timeout in seconds; can be set to: 60, 300, 900, 1800, 3600

icon · ?image data

Base64 1024x1024 png/jpeg/gif image for the guild icon

splash · ?image data

Base64 16:9 png/jpeg image for the guild splash

discovery_splash · ?image data

Base64 16:9 png/jpeg image for the guild discovery splash

banner · ?image data

Base64 16:9 png/jpeg image for the guild banner

system_channel_id · ?snowflake

The id of the channel where guild notices are posted

system_channel_flags · integer

System channel flags

rules_channel_id · ?snowflake

The id of the channel where Community guilds display rules

public_updates_channel_id · ?snowflake

The id of the channel where admins and moderators receive notices from Discord

preferred_locale · ?string

The preferred locale of a Community guild; defaults to “en-US”

features · array of strings

Enabled guild features

description · ?string

The description for the guild

premium_progress_bar_enabled · boolean

Whether the guild’s boost progress bar should be enabled

safety_alerts_channel_id · ?snowflake

The id of the channel where admins and moderators receive safety alerts from Discord

Get guild channels

GET /guilds/{guild.id}/channels

Returns a list of guild channel objects. Does not include threads.

Create guild channel

POST /guilds/{guild.id}/channels

Create a new channel object for the guild. Requires the MANAGE_CHANNELS permission. Returns the new channel object on success.

This endpoint supports the X-Audit-Log-Reason header.

JSON params

Field	Type	Description	Channel type
name	string	Channel name (1-100 characters)	All
type	integer	The type of channel	All
topic	string	Channel topic (0-1024 characters)	Text, Announcement, Forum, Media
bitrate	integer	Bitrate in bits per second; min 8000	Voice, Stage
user_limit	integer	The user limit of the voice channel	Voice, Stage
rate_limit_per_user	integer	Slowmode in seconds (0-21600)	Text, Voice, Stage, Forum, Media
position	integer	Sorting position of the channel	All
permission_overwrites	array	The channel’s permission overwrites	All
parent_id	snowflake	ID of the parent category for a channel	Text, Voice, Announcement, Stage, Forum, Media
nsfw	boolean	Whether the channel is age-restricted	Text, Voice, Announcement, Stage, Forum
rtc_region	string	Channel voice region id	Voice, Stage
video_quality_mode	integer	Camera video quality mode	Voice, Stage
default_auto_archive_duration	integer	Default thread auto-archive duration in minutes	Text, Announcement, Forum, Media
default_reaction_emoji	object	Emoji to show in the add reaction button on a thread	Forum, Media
available_tags	array	Set of tags that can be used in a forum/media channel	Forum, Media
default_sort_order	integer	Default sort order type	Forum, Media
default_forum_layout	integer	Default forum layout view	Forum
default_thread_rate_limit_per_user	integer	Initial rate limit for newly created threads	Text, Announcement, Forum, Media

Modify guild channel positions

PATCH /guilds/{guild.id}/channels

Modify the positions of a set of channel objects for the guild. Requires MANAGE_CHANNELS permission. Returns a 204 empty response on success.

JSON params (array)

id · snowflake · required

Channel id

position · ?integer

Sorting position of the channel

lock_permissions · ?boolean

Syncs the permission overwrites with the new parent, if moving to a new category

parent_id · ?snowflake

The new parent ID for the channel that is moved

List active guild threads

GET /guilds/{guild.id}/threads/active

Returns all active threads in the guild, including public and private threads. Threads are ordered by their id, in descending order.

Get guild member

GET /guilds/{guild.id}/members/{user.id}

Returns a guild member object for the specified user.

List guild members

GET /guilds/{guild.id}/members

Returns a list of guild member objects that are members of the guild.

This endpoint is restricted according to whether the GUILD_MEMBERS Privileged Intent is enabled for your application.

Query string params

limit · integer · default: "1"

Max number of members to return (1-1000)

after · snowflake · default: "0"

The highest user id in the previous page

Search guild members

GET /guilds/{guild.id}/members/search

Returns a list of guild member objects whose username or nickname starts with a provided string.

Query string params

query · string · required

Query string to match username(s) and nickname(s) against

limit · integer · default: "1"

Max number of members to return (1-1000)

Add guild member

PUT /guilds/{guild.id}/members/{user.id}

Adds a user to the guild, provided you have a valid OAuth2 access token for the user with the guilds.join scope. Returns a 201 Created with the guild member as the body, or 204 No Content if the user is already a member.

JSON params

access_token · string · required

An OAuth2 access token granted with the guilds.join scope for the user you want to add

nick · string

Value to set user’s nickname to. Requires MANAGE_NICKNAMES permission.

roles · array of snowflakes

Array of role ids the member is assigned. Requires MANAGE_ROLES permission.

mute · boolean

Whether the user is muted in voice channels. Requires MUTE_MEMBERS permission.

deaf · boolean

Whether the user is deafened in voice channels. Requires DEAFEN_MEMBERS permission.

Modify guild member

PATCH /guilds/{guild.id}/members/{user.id}

Modify attributes of a guild member. Returns a 200 OK with the guild member as the body.

This endpoint supports the X-Audit-Log-Reason header.

JSON params

nick · string

Value to set user’s nickname to. Requires MANAGE_NICKNAMES permission.

roles · array of snowflakes

Array of role ids the member is assigned. Requires MANAGE_ROLES permission.

mute · boolean

Whether the user is muted in voice channels. Requires MUTE_MEMBERS permission.

deaf · boolean

Whether the user is deafened in voice channels. Requires DEAFEN_MEMBERS permission.

channel_id · snowflake

ID of channel to move user to (if they are connected to voice). Requires MOVE_MEMBERS permission.

communication_disabled_until · ISO8601 timestamp

When the user’s timeout will expire (up to 28 days in the future). Set to null to remove timeout. Requires MODERATE_MEMBERS permission.

flags · integer

Guild member flags

Modify current member

PATCH /guilds/{guild.id}/members/@me

Modifies the current member in a guild. Returns a 200 with the updated member object on success.

This endpoint supports the X-Audit-Log-Reason header.

JSON params

nick · ?string

Value to set user’s nickname to. Requires CHANGE_NICKNAME permission.

banner · ?string

Data URI base64 encoded banner image

avatar · ?string

Data URI base64 encoded avatar image

bio · ?string

Guild member bio

Remove guild member

DELETE /guilds/{guild.id}/members/{user.id}

Remove a member from a guild. Requires KICK_MEMBERS permission. Returns a 204 empty response on success.

Get guild bans

GET /guilds/{guild.id}/bans

Returns a list of ban objects for the users banned from this guild. Requires the BAN_MEMBERS permission.

Query string params

limit · number · default: "1000"

Number of users to return (up to maximum 1000)

before · snowflake

Consider only users before given user id

after · snowflake

Consider only users after given user id

Get guild ban

GET /guilds/{guild.id}/bans/{user.id}

Returns a ban object for the given user or a 404 if the ban cannot be found. Requires the BAN_MEMBERS permission.

Create guild ban

PUT /guilds/{guild.id}/bans/{user.id}

Create a guild ban, and optionally delete previous messages sent by the banned user. Requires the BAN_MEMBERS permission. Returns a 204 empty response on success.

This endpoint supports the X-Audit-Log-Reason header.

JSON params

delete_message_seconds · integer · default: "0"

Number of seconds to delete messages for, between 0 and 604800 (7 days)

Remove guild ban

DELETE /guilds/{guild.id}/bans/{user.id}

Remove the ban for a user. Requires the BAN_MEMBERS permission. Returns a 204 empty response on success.

Bulk guild ban

POST /guilds/{guild.id}/bulk-ban

Ban up to 200 users from a guild. Requires both the BAN_MEMBERS and MANAGE_GUILD permissions. Returns a 200 response on success, including banned_users with the IDs of the banned users and failed_users with IDs that could not be banned.

Add guild member role

PUT /guilds/{guild.id}/members/{user.id}/roles/{role.id}

Adds a role to a guild member. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success.

Remove guild member role

DELETE /guilds/{guild.id}/members/{user.id}/roles/{role.id}

Removes a role from a guild member. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success.