Guild Object
Guild Structure
Fields specific to the 
GUILD_CREATE event are listed in the Gateway Events documentation.| Field | Type | Description | 
|---|---|---|
| id | snowflake | guild id | 
| name | string | guild name (2-100 characters, excluding trailing and leading whitespace) | 
| icon | ?string | icon hash | 
| icon_hash? | ?string | icon hash, returned when in the template object | 
| splash | ?string | splash hash | 
| discovery_splash | ?string | discovery splash hash; only present for guilds with the “DISCOVERABLE” feature | 
| owner? * | boolean | true if the user is the owner of the guild | 
| owner_id | snowflake | id of owner | 
| permissions? * | string | total permissions for the user in the guild (excludes overwrites and implicit permissions) | 
| region? ** | ?string | voice region id for the guild (deprecated) | 
| afk_channel_id | ?snowflake | id of afk channel | 
| afk_timeout | integer | 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 nullif set to no invite | 
| verification_level | integer | verification level required for the guild | 
| default_message_notifications | integer | default message notifications level | 
| explicit_content_filter | integer | explicit content filter level | 
| roles | array of role objects | roles in the guild | 
| emojis | array of emoji objects | custom guild emojis | 
| features | array of guild feature strings | enabled guild features | 
| mfa_level | integer | required MFA level for the guild | 
| application_id | ?snowflake | application id of the guild creator if it is bot-created | 
| system_channel_id | ?snowflake | the id of the channel where guild notices such as welcome messages and boost events are posted | 
| system_channel_flags | integer | system channel flags | 
| rules_channel_id | ?snowflake | 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 ( nullis always returned, apart from the largest of guilds) | 
| max_members? | integer | the maximum number of members for the guild | 
| vanity_url_code | ?string | the vanity url code for the guild | 
| description | ?string | the description of a guild | 
| banner | ?string | banner hash | 
| premium_tier | integer | premium tier (Server Boost level) | 
| premium_subscription_count? | integer | the number of boosts this guild currently has | 
| preferred_locale | string | the preferred locale of a Community guild; used in server discovery and notices from Discord, and sent in interactions; defaults to “en-US” | 
| public_updates_channel_id | ?snowflake | 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 from the GET /guilds/<id>and/users/@me/guildsendpoints whenwith_countsistrue | 
| approximate_presence_count? | integer | approximate number of non-offline members in this guild, returned from the GET /guilds/<id>and/users/@me/guildsendpoints whenwith_countsistrue | 
| welcome_screen? | welcome screen object | the welcome screen of a Community guild, shown to new members, returned in an Invite’s guild object | 
| nsfw_level | integer | guild NSFW level | 
| stickers? | array of sticker objects | custom guild stickers | 
| premium_progress_bar_enabled | boolean | whether the guild has the boost progress bar enabled | 
| safety_alerts_channel_id | ?snowflake | the id of the channel where admins and moderators of Community guilds receive safety alerts from Discord | 
| incidents_data | ?incidents data object | 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, stage channels and discovery, and receives community updates | 
| 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 or the directory | 
| RAID_ALERTS_DISABLED | guild has disabled alerts for join raids in the configured 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 (previously VIP voice servers) | 
| 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
| Features | 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 | 
Example Guild
Unavailable Guild Object
A partial guild object. Represents an Offline Guild, or a Guild whose information has not been provided through Guild Create events during the Gateway connect.Example Unavailable Guild
Guild Preview Object
Guild Preview Structure
| Field | Type | Description | 
|---|---|---|
| id | snowflake | guild id | 
| name | string | guild name (2-100 characters) | 
| icon | ?string | icon hash | 
| splash | ?string | splash hash | 
| discovery_splash | ?string | discovery splash hash | 
| emojis | array of emoji objects | custom guild emojis | 
| features | array of guild feature strings | enabled guild features | 
| approximate_member_count | integer | approximate number of members in this guild | 
| approximate_presence_count | integer | approximate number of online members in this guild | 
| description | ?string | the description for the guild | 
| stickers | array of sticker objects | custom guild stickers | 
Example Guild Preview
Guild Widget Settings Object
Guild Widget Settings Structure
| Field | Type | Description | 
|---|---|---|
| enabled | boolean | whether the widget is enabled | 
| channel_id | ?snowflake | the widget channel id | 
Example Guild Widget Settings
Guild Widget Object
Guild Widget Structure
| Field | Type | Description | 
|---|---|---|
| id | snowflake | guild id | 
| name | string | guild name (2-100 characters) | 
| instant_invite | ?string | instant invite for the guilds specified widget invite channel | 
| channels | array of partial channel objects | voice and stage channels which are accessible by @everyone | 
| members | array of partial user objects | special widget user objects that includes users presence (Limit 100) | 
| presence_count | integer | number of online members in this guild | 
The fields 
id, discriminator and avatar are anonymized to prevent abuse.Example Guild Widget
Guild Member Object
Guild Member Structure
| Field | Type | Description | 
|---|---|---|
| user? | user object | the user this guild member represents | 
| 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 | array of role object ids | 
| joined_at | ?ISO8601 timestamp | when the user joined the guild | 
| premium_since? | ?ISO8601 timestamp | when the user started boosting the guild | 
| deaf | boolean | whether the user is deafened in voice channels | 
| mute | boolean | whether the user is muted in voice channels | 
| flags | integer | 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 | 
The field 
user won’t be included in the member object attached to MESSAGE_CREATE and MESSAGE_UPDATE gateway events.In 
GUILD_ events, pending will always be included as true or false. In non GUILD_ events which can only be triggered by non-pending users, pending will not be included.Member objects retrieved from 
VOICE_STATE_UPDATE events will have joined_at set as null if the member was invited as a guest.Example Guild Member
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 | 
BYPASSES_VERIFICATION allows a member who does not meet verification requirements to participate in a server.
Integration Object
Integration Structure
| Field | Type | Description | 
|---|---|---|
| id | snowflake | integration id | 
| name | string | integration name | 
| type | string | integration type (twitch, youtube, discord, or guild_subscription) | 
| enabled | boolean | is this integration enabled | 
| syncing? * | boolean | is this integration syncing | 
| role_id? * | snowflake | id that this integration uses for “subscribers” | 
| enable_emoticons? * | boolean | whether emoticons should be synced for this integration (twitch only currently) | 
| expire_behavior? * | integration expire behavior | the behavior of expiring subscribers | 
| expire_grace_period? * | integer | the grace period (in days) before expiring subscribers | 
| user? | user object | user for this integration | 
| account | account object | integration account information | 
| synced_at? * | ISO8601 timestamp | when this integration was last synced | 
| subscriber_count? * | integer | how many subscribers this integration has | 
| revoked? * | boolean | has this integration been revoked | 
| application? | application object | The bot/OAuth2 application for discord integrations | 
| scopes? | array of OAuth2 scopes | the scopes the application has been authorized for | 
Some older integrations may not have an attached user.
Integration Expire Behaviors
| Value | Name | 
|---|---|
| 0 | Remove role | 
| 1 | Kick | 
Integration Account Object
Integration Account Structure
| Field | Type | Description | 
|---|---|---|
| id | string | id of the account | 
| name | string | name of the account | 
Integration Application Object
Integration Application Structure
Ban Object
Ban Structure
| Field | Type | Description | 
|---|---|---|
| reason | ?string | the reason for the ban | 
| user | user object | the banned user | 
Example Ban
Welcome Screen Object
Welcome Screen Structure
| Field | Type | Description | 
|---|---|---|
| description | ?string | the server description shown in the welcome screen | 
| welcome_channels | array of welcome screen channel objects | the channels shown in the welcome screen, up to 5 | 
Welcome Screen Channel Structure
| Field | Type | Description | 
|---|---|---|
| channel_id | snowflake | the channel’s id | 
| description | string | the description shown for the channel | 
| emoji_id | ?snowflake | the emoji id, if the emoji is custom | 
| emoji_name | ?string | the emoji name if custom, the unicode character if standard, or nullif no emoji is set | 
Example Welcome Screen
Guild Onboarding Object
Represents the onboarding flow for a guild.Guild Onboarding Structure
| Field | Type | Description | 
|---|---|---|
| guild_id | snowflake | ID of the guild this onboarding is part of | 
| prompts | array of onboarding prompt objects | Prompts shown during onboarding and in customize community | 
| default_channel_ids | array of snowflakes | Channel IDs that members get opted into automatically | 
| enabled | boolean | Whether onboarding is enabled in the guild | 
| mode | onboarding mode | Current mode of onboarding | 
Onboarding Prompt Structure
| Field | Type | Description | 
|---|---|---|
| id | snowflake | ID of the prompt | 
| type | prompt type | Type of prompt | 
| options | array of prompt option objects | Options available within the prompt | 
| title | string | Title of the prompt | 
| single_select | boolean | Indicates whether users are limited to selecting one option for the prompt | 
| required | boolean | Indicates whether the prompt is required before a user completes the onboarding flow | 
| in_onboarding | boolean | Indicates whether the prompt is present in the onboarding flow. If false, the prompt will only appear in the Channels & Roles tab | 
Prompt Option Structure
| Field | Type | Description | 
|---|---|---|
| id | snowflake | ID of the prompt option | 
| channel_ids | array of snowflakes | IDs for channels a member is added to when the option is selected | 
| role_ids | array of snowflakes | IDs for roles assigned to a member when the option is selected | 
| emoji? | emoji object | Emoji of the option (see below) | 
| emoji_id? | snowflake | Emoji ID of the option (see below) | 
| emoji_name? | string | Emoji name of the option (see below) | 
| emoji_animated? | boolean | Whether the emoji is animated (see below) | 
| title | string | Title of the option | 
| description | ?string | Description of the option | 
When creating or updating a prompt option, the 
emoji_id, emoji_name, and emoji_animated fields must be used instead of the emoji object.Onboarding Mode
Defines the criteria used to satisfy Onboarding constraints that are required for enabling.| Name | Value | Description | 
|---|---|---|
| ONBOARDING_DEFAULT | 0 | Counts only Default Channels towards constraints | 
| ONBOARDING_ADVANCED | 1 | Counts Default Channels and Questions towards constraints | 
Prompt Types
| Name | Value | 
|---|---|
| MULTIPLE_CHOICE | 0 | 
| DROPDOWN | 1 | 
Example Guild Onboarding
Membership Screening Object
In guilds with Membership Screening enabled, when a member joins, Guild Member Add will be emitted but they will initially be restricted from doing any actions in the guild, andpending will be true in the member object. When the member completes the screening, Guild Member Update will be emitted and pending will be false.
We are making significant changes to the Membership Screening API specifically related to getting and editing the Membership Screening object. Long story short is that it can be improved. As such, we have removed those documentation. There will not be any changes to how pending members work, as outlined above. That behavior will stay the same.
Incidents Data Object
Incidents Data Structure
| Field | Type | Description | 
|---|---|---|
| invites_disabled_until | ?ISO8601 timestamp | when invites get enabled again | 
| dms_disabled_until | ?ISO8601 timestamp | 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 | 
Example Incidents Data
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
| Field | Type | Description | Required | Default | 
|---|---|---|---|---|
| with_counts? | boolean | when true, will return approximate member and presence counts for the guild | false | false | 
Example Response
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. Fires a Guild Update Gateway event.
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
| Field | Type | Description | 
|---|---|---|
| name | string | guild name | 
| region | ?string | guild voice region id (deprecated) | 
| 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 (can be animated gif when the server has the ANIMATED_ICONfeature) | 
| splash | ?image data | base64 16:9 png/jpeg image for the guild splash (when the server has the INVITE_SPLASHfeature) | 
| discovery_splash | ?image data | base64 16:9 png/jpeg image for the guild discovery splash (when the server has the DISCOVERABLEfeature) | 
| banner | ?image data | base64 16:9 png/jpeg image for the guild banner (when the server has the BANNERfeature; can be animated gif when the server has theANIMATED_BANNERfeature) | 
| system_channel_id | ?snowflake | the id of the channel where guild notices such as welcome messages and boost events are posted | 
| system_channel_flags | integer | system channel flags | 
| rules_channel_id | ?snowflake | the id of the channel where Community guilds display rules and/or guidelines | 
| public_updates_channel_id | ?snowflake | the id of the channel where admins and moderators of Community guilds receive notices from Discord | 
| preferred_locale | ?string | the preferred locale of a Community guild used in server discovery and notices from Discord; defaults to “en-US” | 
| features | array of guild feature 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 of Community guilds 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. If setting permission overwrites, only permissions your bot has in the guild can be allowed/denied. Setting MANAGE_ROLES permission in channels is only possible for guild administrators. Returns the new channel object on success. Fires a Channel Create Gateway event.
All parameters to this endpoint are optional and nullable excluding 
nameThis 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 | the bitrate (in bits) of the voice or stage channel; min 8000 | Voice, Stage | 
| user_limit | integer | the user limit of the voice channel | Voice, Stage | 
| rate_limit_per_user | integer | amount of seconds a user has to wait before sending another message (0-21600); bots, as well as users with the permission manage_messagesormanage_channel, are unaffected | Text, Voice, Stage, Forum, Media | 
| position | integer | sorting position of the channel (channels with the same position are sorted by id) | All | 
| permission_overwrites** | array of partial overwrite objects | 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 nsfw | Text, Voice, Announcement, Stage, Forum | 
| rtc_region | string | channel voice region id of the voice or stage channel, automatic when set to null | Voice, Stage | 
| video_quality_mode | integer | the camera video quality mode of the voice channel | Voice, Stage | 
| default_auto_archive_duration | integer | the default duration that the clients use (not the API) for newly created threads in the channel, in minutes, to automatically archive the thread after recent activity | Text, Announcement, Forum, Media | 
| default_reaction_emoji | default reaction object | emoji to show in the add reaction button on a thread in a GUILD_FORUMor aGUILD_MEDIAchannel | Forum, Media | 
| available_tags | array of tag objects | set of tags that can be used in a GUILD_FORUMor aGUILD_MEDIAchannel | Forum, Media | 
| default_sort_order | integer | the default sort order type used to order posts in GUILD_FORUMandGUILD_MEDIAchannels | Forum, Media | 
| default_forum_layout | integer | the default forum layout view used to display posts in GUILD_FORUMchannels | Forum | 
| default_thread_rate_limit_per_user | integer | the initial rate_limit_per_userto set on newly created threads in a channel. this field is copied to the thread at creation time and does not live update. | Text, Announcement, Forum, Media | 
VIP_REGIONS guild feature can set up to 384000. For stage channels, bitrate can be set up to 64000.
** In each overwrite object, the allow and deny keys can be omitted or set to null, which both default to "0".
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. Fires multiple Channel Update Gateway events.
Only channels to be modified are required.
JSON Params
| Field | Type | Description | 
|---|---|---|
| id | snowflake | channel id | 
| position? | ?integer | sorting position of the channel (channels with the same position are sorted by id) | 
| 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.
Response Body
| Field | Type | Description | 
|---|---|---|
| threads | array of channel objects | the active threads | 
| members | array of thread members objects | a thread member object for each returned thread the current user has joined | 
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.All parameters to this endpoint are optional
Query String Params
| Field | Type | Description | Default | 
|---|---|---|---|
| limit | integer | max number of members to return (1-1000) | 1 | 
| after | snowflake | the highest user id in the previous page | 0 | 
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.
All parameters to this endpoint except for 
query are optionalQuery String Params
| Field | Type | Description | Default | 
|---|---|---|---|
| query | string | Query string to match username(s) and nickname(s) against. | |
| limit | integer | max number of members to return (1-1000) | 1 | 
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 of the guild. Fires a Guild Member Add Gateway event.
For guilds with Membership Screening enabled, this endpoint will default to adding new members as pending in the guild member object. Members that are pending will have to complete membership screening before they become full members that can talk.
All parameters to this endpoint except for 
access_token are optional.The Authorization header must be a Bot token (belonging to the same application used for authorization), and the bot must be a member of the guild with 
CREATE_INSTANT_INVITE permission.JSON Params
| Field | Type | Description | Permission | 
|---|---|---|---|
| access_token | string | an oauth2 access token granted with the guilds.jointo the bot’s application for the user you want to add to the guild | |
| nick | string | value to set user’s nickname to | MANAGE_NICKNAMES | 
| roles | array of snowflakes | array of role ids the member is assigned | MANAGE_ROLES | 
| mute | boolean | whether the user is muted in voice channels | MUTE_MEMBERS | 
| deaf | boolean | whether the user is deafened in voice channels | DEAFEN_MEMBERS | 
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. Fires a Guild Member Update Gateway event. If the channel_id is set to null, this will force the target user to be disconnected from voice.
All parameters to this endpoint are optional and nullable. When moving members to channels, the API user must have permissions to both connect to the channel and have the 
MOVE_MEMBERS permission.This endpoint supports the 
X-Audit-Log-Reason header.JSON Params
| Field | Type | Description | Permission | 
|---|---|---|---|
| nick | string | value to set user’s nickname to | MANAGE_NICKNAMES | 
| roles | array of snowflakes | array of role ids the member is assigned | MANAGE_ROLES | 
| mute | boolean | whether the user is muted in voice channels. Will throw a 400 error if the user is not in a voice channel | MUTE_MEMBERS | 
| deaf | boolean | whether the user is deafened in voice channels. Will throw a 400 error if the user is not in a voice channel | DEAFEN_MEMBERS | 
| channel_id | snowflake | id of channel to move user to (if they are connected to voice) | MOVE_MEMBERS | 
| communication_disabled_until | ISO8601 timestamp | when the user’s timeout will expire and the user will be able to communicate in the guild again (up to 28 days in the future), set to null to remove timeout. Will throw a 403 error if the user has the ADMINISTRATOR permission or is the owner of the guild | MODERATE_MEMBERS | 
| flags | integer | guild member flags | MANAGE_GUILD or MANAGE_ROLES or (MODERATE_MEMBERS and KICK_MEMBERS and BAN_MEMBERS) | 
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. Fires a Guild Member Update Gateway event.
This endpoint supports the 
X-Audit-Log-Reason header.JSON Params
| Field | Type | Description | Permission | 
|---|---|---|---|
| nick? | ?string | value to set user’s nickname to | CHANGE_NICKNAME | 
| banner? | ?string | data URI base64 encoded banner image | |
| avatar? | ?string | data URI base64 encoded avatar image | |
| bio? | ?string | guild member bio | 
Modify Current User Nick
PATCH/guilds/{guild.id}/members/@me/nick
Deprecated in favor of Modify Current Member.
This endpoint supports the 
X-Audit-Log-Reason header.JSON Params
| Field | Type | Description | Permission | 
|---|---|---|---|
| nick? | ?string | value to set user’s nickname to | CHANGE_NICKNAME | 
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. Fires a Guild Member Update Gateway event.
This endpoint supports the 
X-Audit-Log-Reason header.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. Fires a Guild Member Update Gateway event.
This endpoint supports the 
X-Audit-Log-Reason header.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. Fires a Guild Member Remove Gateway event.
This endpoint supports the 
X-Audit-Log-Reason header.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
| Field | Type | Description | Default | 
|---|---|---|---|
| limit? | number | number of users to return (up to maximum 1000) | 1000 | 
| before? * | snowflake | consider only users before given user id | null | 
| after? * | snowflake | consider only users after given user id | null | 
before and after for pagination. Users will always be returned in ascending order by user.id. If both before and after are provided, only before is respected.
Get Guild Ban
GET/guilds/{guild.id}/bans/{user.id}
Returns a ban object for the given user or a 404 not found 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. Fires a Guild Ban Add Gateway event.
This endpoint supports the 
X-Audit-Log-Reason header.JSON Params
| Field | Type | Description | Default | 
|---|---|---|---|
| delete_message_days? | integer | number of days to delete messages for (0-7) (deprecated) | 0 | 
| delete_message_seconds? | integer | number of seconds to delete messages for, between 0 and 604800 (7 days) | 0 | 
Remove Guild Ban
DELETE/guilds/{guild.id}/bans/{user.id}
Remove the ban for a user. Requires the BAN_MEMBERS permissions. Returns a 204 empty response on success. Fires a Guild Ban Remove Gateway event.
This endpoint supports the 
X-Audit-Log-Reason header.Bulk Guild Ban
POST/guilds/{guild.id}/bulk-ban
Ban up to 200 users from a guild, and optionally delete previous messages sent by the banned users. Requires both the BAN_MEMBERS and MANAGE_GUILD permissions. Returns a 200 response on success, including the fields banned_users with the IDs of the banned users and failed_users with IDs that could not be banned or were already banned.
This endpoint supports the 
X-Audit-Log-Reason header.JSON Params
| Field | Type | Description | Default | 
|---|---|---|---|
| user_ids | array of snowflakes | list of user ids to ban (max 200) | |
| delete_message_seconds? | integer | number of seconds to delete messages for, between 0 and 604800 (7 days) | 0 | 
Bulk Ban Response
On success, this endpoint returns a 200 success response with the following body.| Field | Type | Description | 
|---|---|---|
| banned_users | array of snowflakes | list of user ids, that were successfully banned | 
| failed_users | array of snowflakes | list of user ids, that were not banned | 
If none of the users could be banned, an error response code 
500000: Failed to ban users is returned instead.Get Guild Roles
GET/guilds/{guild.id}/roles
Returns a list of role objects for the guild.
Get Guild Role
GET/guilds/{guild.id}/roles/{role.id}
Returns a role object for the specified role.
Create Guild Role
POST/guilds/{guild.id}/roles
Create a new role for the guild. Requires the MANAGE_ROLES permission. Returns the new role object on success. Fires a Guild Role Create Gateway event. All JSON params are optional.
This endpoint supports the 
X-Audit-Log-Reason header.JSON Params
| Field | Type | Description | Default | 
|---|---|---|---|
| name | string | name of the role, max 100 characters | ”new role” | 
| permissions | string | bitwise value of the enabled/disabled permissions | @everyone permissions in guild | 
| color* | integer | Deprecated RGB color value | 0 | 
| colors | role colors object | the role’s colors | default role colors object | 
| hoist | boolean | whether the role should be displayed separately in the sidebar | false | 
| icon | ?image data | the role’s icon image (if the guild has the ROLE_ICONSfeature) | null | 
| unicode_emoji | ?string | the role’s unicode emoji as a standard emoji (if the guild has the ROLE_ICONSfeature) | null | 
| mentionable | boolean | whether the role should be mentionable | false | 
color will still be returned by the API, but using the colors field is recommended when doing requests.
Modify Guild Role Positions
PATCH/guilds/{guild.id}/roles
Modify the positions of a set of role objects for the guild. Requires the MANAGE_ROLES permission. Returns a list of all of the guild’s role objects on success. Fires multiple Guild Role Update Gateway events.
This endpoint supports the 
X-Audit-Log-Reason header.JSON Params
| Field | Type | Description | 
|---|---|---|
| id | snowflake | role | 
| position? | ?integer | sorting position of the role (roles with the same position are sorted by id) | 
Modify Guild Role
PATCH/guilds/{guild.id}/roles/{role.id}
Modify a guild role. Requires the MANAGE_ROLES permission. Returns the updated role on success. Fires a Guild Role Update Gateway event.
All parameters to this endpoint are optional and nullable.
This endpoint supports the 
X-Audit-Log-Reason header.JSON Params
| Field | Type | Description | 
|---|---|---|
| name | string | name of the role, max 100 characters | 
| permissions | string | bitwise value of the enabled/disabled permissions | 
| color* | integer | Deprecated RGB color value | 
| colors | role colors object | the role’s colors | 
| hoist | boolean | whether the role should be displayed separately in the sidebar | 
| icon | image data | the role’s icon image (if the guild has the ROLE_ICONSfeature) | 
| unicode_emoji | string | the role’s unicode emoji as a standard emoji (if the guild has the ROLE_ICONSfeature) | 
| mentionable | boolean | whether the role should be mentionable | 
color will still be returned by the API, but using the colors field is recommended when doing requests.
Delete Guild Role
DELETE/guilds/{guild.id}/roles/{role.id}
Delete a guild role. Requires the MANAGE_ROLES permission. Returns a 204 empty response on success. Fires a Guild Role Delete Gateway event.
This endpoint supports the 
X-Audit-Log-Reason header.Get Guild Prune Count
GET/guilds/{guild.id}/prune
Returns an object with one pruned key indicating the number of members that would be removed in a prune operation. Requires the MANAGE_GUILD and KICK_MEMBERS permissions.
By default, prune will not remove users with roles. You can optionally include specific roles in your prune by providing the include_roles parameter. Any inactive user that has a subset of the provided role(s) will be counted in the prune and users with additional roles will not.
Query String Params
| Field | Type | Description | Default | 
|---|---|---|---|
| days | integer | number of days to count prune for (1-30) | 7 | 
| include_roles | string; comma-delimited array of snowflakes | role(s) to include | none | 
Begin Guild Prune
POST/guilds/{guild.id}/prune
Begin a prune operation. Requires the MANAGE_GUILD and KICK_MEMBERS permissions. Returns an object with one pruned key indicating the number of members that were removed in the prune operation. For large guilds it’s recommended to set the compute_prune_count option to false, forcing pruned to null. Fires multiple Guild Member Remove Gateway events.
By default, prune will not remove users with roles. You can optionally include specific roles in your prune by providing the include_roles parameter. Any inactive user that has a subset of the provided role(s) will be included in the prune and users with additional roles will not.
This endpoint supports the 
X-Audit-Log-Reason header.JSON Params
| Field | Type | Description | Default | 
|---|---|---|---|
| days | integer | number of days to prune (1-30) | 7 | 
| compute_prune_count | boolean | whether prunedis returned, discouraged for large guilds | true | 
| include_roles | array of snowflakes | role(s) to include | none | 
| reason? | string | reason for the prune (deprecated) | 
Get Guild Voice Regions
GET/guilds/{guild.id}/regions
Returns a list of voice region objects for the guild. Unlike the similar /voice route, this returns VIP servers when the guild is VIP-enabled.
Get Guild Invites
GET/guilds/{guild.id}/invites
Returns a list of invite objects. Requires the MANAGE_GUILD or VIEW_AUDIT_LOG permission. Invite Metadata is included with the MANAGE_GUILD permission.
Get Guild Integrations
GET/guilds/{guild.id}/integrations
Returns a list of integration objects for the guild. Requires the MANAGE_GUILD permission.
This endpoint returns a maximum of 50 integrations. If a guild has more integrations, they cannot be accessed.
Delete Guild Integration
DELETE/guilds/{guild.id}/integrations/{integration.id}
Delete the attached integration object for the guild. Deletes any associated webhooks and kicks the associated bot if there is one. Requires the MANAGE_GUILD permission. Returns a 204 empty response on success. Fires Guild Integrations Update and Integration Delete Gateway events.
This endpoint supports the 
X-Audit-Log-Reason header.Get Guild Widget Settings
GET/guilds/{guild.id}/widget
Returns a guild widget settings object. Requires the MANAGE_GUILD permission.
Modify Guild Widget
PATCH/guilds/{guild.id}/widget
Modify a guild widget settings object for the guild. All attributes may be passed in with JSON and modified. Requires the MANAGE_GUILD permission. Returns the updated guild widget settings object. Fires a Guild Update Gateway event.
This endpoint supports the 
X-Audit-Log-Reason header.Get Guild Widget
GET/guilds/{guild.id}/widget.json
Returns the widget for the guild. Fires an Invite Create Gateway event when an invite channel is defined and a new Invite is generated.
Get Guild Vanity URL
GET/guilds/{guild.id}/vanity-url
Returns a partial invite object for guilds with that feature enabled. Requires the MANAGE_GUILD permission. code will be null if a vanity url for the guild is not set.
This endpoint is required to get the usage count of the vanity invite, but the invite code can be accessed as 
vanity_url_code in the guild object without having the MANAGE_GUILD permission.Example Partial Invite Object
Get Guild Widget Image
GET/guilds/{guild.id}/widget.png
Returns a PNG image widget for the guild. Requires no permissions or authentication.
All parameters to this endpoint are optional.
Query String Params
| Field | Type | Description | Default | 
|---|---|---|---|
| style | string | style of the widget image returned (see below) | shield | 
Widget Style Options
| Value | Description | Example | 
|---|---|---|
| shield | shield style widget with Discord icon and guild members online count | Example | 
| banner1 | large image with guild icon, name and online count. “POWERED BY DISCORD” as the footer of the widget | Example | 
| banner2 | smaller widget style with guild icon, name and online count. Split on the right with Discord logo | Example | 
| banner3 | large image with guild icon, name and online count. In the footer, Discord logo on the left and “Chat Now” on the right | Example | 
| banner4 | large Discord logo at the top of the widget. Guild icon, name and online count in the middle portion of the widget and a “JOIN MY SERVER” button at the bottom | Example | 
Get Guild Welcome Screen
GET/guilds/{guild.id}/welcome-screen
Returns the Welcome Screen object for the guild. If the welcome screen is not enabled, the MANAGE_GUILD permission is required.
Modify Guild Welcome Screen
PATCH/guilds/{guild.id}/welcome-screen
Modify the guild’s Welcome Screen. Requires the MANAGE_GUILD permission. Returns the updated Welcome Screen object. May fire a Guild Update Gateway event.
All parameters to this endpoint are optional and nullable
This endpoint supports the 
X-Audit-Log-Reason header.JSON Params
| Field | Type | Description | 
|---|---|---|
| enabled | boolean | whether the welcome screen is enabled | 
| welcome_channels | array of welcome screen channel objects | channels linked in the welcome screen and their display options | 
| description | string | the server description to show in the welcome screen | 
Get Guild Onboarding
GET/guilds/{guild.id}/onboarding
Returns the Onboarding object for the guild.
Modify Guild Onboarding
PUT/guilds/{guild.id}/onboarding
Modifies the onboarding configuration of the guild. Returns a 200 with the Onboarding object for the guild. Requires the MANAGE_GUILD and MANAGE_ROLES permissions.
Onboarding enforces constraints when enabled. These constraints are that there must be at least 7 Default Channels and at least 5 of them must allow sending messages to the @everyone role. The 
mode field modifies what is considered when enforcing these constraints.This endpoint supports the 
X-Audit-Log-Reason header.All parameters to this endpoint are optional.
JSON Params
| Field | Type | Description | 
|---|---|---|
| prompts | array of onboarding prompt objects | Prompts shown during onboarding and in customize community | 
| default_channel_ids | array of snowflakes | Channel IDs that members get opted into automatically | 
| enabled | boolean | Whether onboarding is enabled in the guild | 
| mode | onboarding mode | Current mode of onboarding | 
Modify Guild Incident Actions
PUT/guilds/{guild.id}/incident-actions
Modifies the incident actions of the guild. Returns a 200 with the Incidents Data object for the guild. Requires the MANAGE_GUILD permission.
JSON Params
Both 
invites_disabled_until and dms_disabled_until can be enabled for a maximal timespan of 24 hours in the future.| Field | Type | Description | 
|---|---|---|
| invites_disabled_until? | ?ISO8601 timestamp * | when invites will be enabled again | 
| dms_disabled_until? | ?ISO8601 timestamp * | when direct messages will be enabled again | 
null disables the action.