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

Guild Object

Guild Structure
Fields specific to the GUILD_CREATE event are listed in the Gateway Events documentation.
FieldTypeDescription
idsnowflakeguild id
namestringguild name (2-100 characters, excluding trailing and leading whitespace)
icon?stringicon hash
icon_hash??stringicon hash, returned when in the template object
splash?stringsplash hash
discovery_splash?stringdiscovery splash hash; only present for guilds with the “DISCOVERABLE” feature
owner? *booleantrue if the user is the owner of the guild
owner_idsnowflakeid of owner
permissions? *stringtotal permissions for the user in the guild (excludes overwrites and implicit permissions)
region? **?stringvoice region id for the guild (deprecated)
afk_channel_id?snowflakeid of afk channel
afk_timeoutintegerafk timeout in seconds
widget_enabled?booleantrue if the server widget is enabled
widget_channel_id??snowflakethe channel id that the widget will generate an invite to, or null if set to no invite
verification_levelintegerverification level required for the guild
default_message_notificationsintegerdefault message notifications level
explicit_content_filterintegerexplicit content filter level
rolesarray of role objectsroles in the guild
emojisarray of emoji objectscustom guild emojis
featuresarray of guild feature stringsenabled guild features
mfa_levelintegerrequired MFA level for the guild
application_id?snowflakeapplication id of the guild creator if it is bot-created
system_channel_id?snowflakethe id of the channel where guild notices such as welcome messages and boost events are posted
system_channel_flagsintegersystem channel flags
rules_channel_id?snowflakethe id of the channel where Community guilds can display rules and/or guidelines
max_presences??integerthe maximum number of presences for the guild (null is always returned, apart from the largest of guilds)
max_members?integerthe maximum number of members for the guild
vanity_url_code?stringthe vanity url code for the guild
description?stringthe description of a guild
banner?stringbanner hash
premium_tierintegerpremium tier (Server Boost level)
premium_subscription_count?integerthe number of boosts this guild currently has
preferred_localestringthe 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?snowflakethe id of the channel where admins and moderators of Community guilds receive notices from Discord
max_video_channel_users?integerthe maximum amount of users in a video channel
max_stage_video_channel_users?integerthe maximum amount of users in a stage video channel
approximate_member_count?integerapproximate number of members in this guild, returned from the GET /guilds/<id> and /users/@me/guilds endpoints when with_counts is true
approximate_presence_count?integerapproximate number of non-offline members in this guild, returned from the GET /guilds/<id> and /users/@me/guilds endpoints when with_counts is true
welcome_screen?welcome screen objectthe welcome screen of a Community guild, shown to new members, returned in an Invite’s guild object
nsfw_levelintegerguild NSFW level
stickers?array of sticker objectscustom guild stickers
premium_progress_bar_enabledbooleanwhether the guild has the boost progress bar enabled
safety_alerts_channel_id?snowflakethe id of the channel where admins and moderators of Community guilds receive safety alerts from Discord
incidents_data?incidents data objectthe incidents data for this guild
* These fields are only sent when using the GET Current User Guilds endpoint and are relative to the requested user ** This field is deprecated and is replaced by channel.rtc_region
Default Message Notification Level
KeyValueDescription
ALL_MESSAGES0members will receive notifications for all messages by default
ONLY_MENTIONS1members will receive notifications only for messages that @mention them by default
Explicit Content Filter Level
LevelIntegerDescription
DISABLED0media content will not be scanned
MEMBERS_WITHOUT_ROLES1media content sent by members without roles will be scanned
ALL_MEMBERS2media content sent by all members will be scanned
MFA Level
LevelIntegerDescription
NONE0guild has no MFA/2FA requirement for moderation actions
ELEVATED1guild has a 2FA requirement for moderation actions
Verification Level
LevelIntegerDescription
NONE0unrestricted
LOW1must have verified email on account
MEDIUM2must be registered on Discord for longer than 5 minutes
HIGH3must be a member of the server for longer than 10 minutes
VERY_HIGH4must have a verified phone number
Guild NSFW Level
LevelValue
DEFAULT0
EXPLICIT1
SAFE2
AGE_RESTRICTED3
Premium Tier
LevelIntegerDescription
NONE0guild has not unlocked any Server Boost perks
TIER_11guild has unlocked Server Boost level 1 perks
TIER_22guild has unlocked Server Boost level 2 perks
TIER_33guild has unlocked Server Boost level 3 perks
System Channel Flags
FlagValueDescription
SUPPRESS_JOIN_NOTIFICATIONS1 << 0Suppress member join notifications
SUPPRESS_PREMIUM_SUBSCRIPTIONS1 << 1Suppress server boost notifications
SUPPRESS_GUILD_REMINDER_NOTIFICATIONS1 << 2Suppress server setup tips
SUPPRESS_JOIN_NOTIFICATION_REPLIES1 << 3Hide member join sticker reply buttons
SUPPRESS_ROLE_SUBSCRIPTION_PURCHASE_NOTIFICATIONS1 << 4Suppress role subscription purchase and renewal notifications
SUPPRESS_ROLE_SUBSCRIPTION_PURCHASE_NOTIFICATION_REPLIES1 << 5Hide role subscription sticker reply buttons
Guild Features
FeatureDescription
ANIMATED_BANNERguild has access to set an animated guild banner image
ANIMATED_ICONguild has access to set an animated guild icon
APPLICATION_COMMAND_PERMISSIONS_V2guild is using the old permissions configuration behavior
AUTO_MODERATIONguild has set up auto moderation rules
BANNERguild has access to set a guild banner image
COMMUNITYguild can enable welcome screen, Membership Screening, stage channels and discovery, and receives community updates
CREATOR_MONETIZABLE_PROVISIONALguild has enabled monetization
CREATOR_STORE_PAGEguild has enabled the role subscription promo page
DEVELOPER_SUPPORT_SERVERguild has been set as a support server on the App Directory
DISCOVERABLEguild is able to be discovered in the directory
FEATURABLEguild is able to be featured in the directory
INVITES_DISABLEDguild has paused invites, preventing new users from joining
INVITE_SPLASHguild has access to set an invite splash background
MEMBER_VERIFICATION_GATE_ENABLEDguild has enabled Membership Screening
MORE_SOUNDBOARDguild has increased custom soundboard sound slots
MORE_STICKERSguild has increased custom sticker slots
NEWSguild has access to create announcement channels
PARTNEREDguild is partnered
PREVIEW_ENABLEDguild can be previewed before joining via Membership Screening or the directory
RAID_ALERTS_DISABLEDguild has disabled alerts for join raids in the configured safety alerts channel
ROLE_ICONSguild is able to set role icons
ROLE_SUBSCRIPTIONS_AVAILABLE_FOR_PURCHASEguild has role subscriptions that can be purchased
ROLE_SUBSCRIPTIONS_ENABLEDguild has enabled role subscriptions
SOUNDBOARDguild has created soundboard sounds
TICKETED_EVENTS_ENABLEDguild has enabled ticketed events
VANITY_URLguild has access to set a vanity URL
VERIFIEDguild is verified
VIP_REGIONSguild has access to set 384kbps bitrate in voice (previously VIP voice servers)
WELCOME_SCREEN_ENABLEDguild has enabled the welcome screen
GUESTS_ENABLEDguild has access to guest invites
GUILD_TAGSguild has access to set guild tags
ENHANCED_ROLE_COLORSguild is able to set gradient colors to roles
Mutable Guild Features
FeaturesRequired PermissionsEffects
COMMUNITYAdministratorEnables Community Features in the guild
DISCOVERABLEAdministrator*Enables discovery in the guild, making it publicly listed
INVITES_DISABLEDManage GuildPauses all invites/access to the server
RAID_ALERTS_DISABLEDManage GuildDisables alerts for join raids
* Server also must 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",
    "MORE_EMOJI",
    "INVITE_SPLASH",
    "BANNER",
    "COMMUNITY"
  ],
  "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,
  "max_presences": 40000,
  "max_members": 250000,
  "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"
}

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
{
  "id": "41771983423143937",
  "unavailable": true
}

Guild Preview Object

Guild Preview Structure
FieldTypeDescription
idsnowflakeguild id
namestringguild name (2-100 characters)
icon?stringicon hash
splash?stringsplash hash
discovery_splash?stringdiscovery splash hash
emojisarray of emoji objectscustom guild emojis
featuresarray of guild feature stringsenabled guild features
approximate_member_countintegerapproximate number of members in this guild
approximate_presence_countintegerapproximate number of online members in this guild
description?stringthe description for the guild
stickersarray of sticker objectscustom guild stickers
Example Guild Preview
{
  "id": "197038439483310086",
  "name": "Discord Testers",
  "icon": "f64c482b807da4f539cff778d174971c",
  "splash": null,
  "discovery_splash": null,
  "emojis": [],
  "features": [
    "DISCOVERABLE",
    "VANITY_URL",
    "ANIMATED_ICON",
    "INVITE_SPLASH",
    "NEWS",
    "COMMUNITY",
    "BANNER",
    "VERIFIED",
    "MORE_EMOJI"
  ],
  "approximate_member_count": 60814,
  "approximate_presence_count": 20034,
  "description": "The official place to report Discord Bugs!",
  "stickers": []
}

Guild Widget Settings Object

Guild Widget Settings Structure
FieldTypeDescription
enabledbooleanwhether the widget is enabled
channel_id?snowflakethe widget channel id
Example Guild Widget Settings
{
  "enabled": true,
  "channel_id": "41771983444115456"
}

Guild Widget Object

Guild Widget Structure
FieldTypeDescription
idsnowflakeguild id
namestringguild name (2-100 characters)
instant_invite?stringinstant invite for the guilds specified widget invite channel
channelsarray of partial channel objectsvoice and stage channels which are accessible by @everyone
membersarray of partial user objectsspecial widget user objects that includes users presence (Limit 100)
presence_countintegernumber of online members in this guild
The fields id, discriminator and avatar are anonymized to prevent abuse.
Example Guild Widget
{
  "id": "290926798626999250",
  "name": "Test Server",
  "instant_invite": "https://discord.com/invite/abcdefg",
  "channels": [
    {
      "id": "705216630279993882",
      "name": "elephant",
      "position": 2
    },
    {
      "id": "669583461748992190",
      "name": "groovy-music",
      "position": 1
    }
  ],
  "members": [
    {
      "id": "0",
      "username": "1234",
      "discriminator": "0000",
      "avatar": null,
      "status": "online",
      "avatar_url": "https://cdn.discordapp.com/widget-avatars/FfvURgcr3Za92K3JtoCppqnYMppMDc5B-Rll74YrGCU/C-1DyBZPQ6t5q2RuATFuMFgq0_uEMZVzd_6LbGN_uJKvZflobA9diAlTjhf6CAESLLeTuu4dLuHFWOb_PNLteooNfhC4C6k5QgAGuxEOP12tVVVCvX6t64k14PMXZrGTDq8pWZhukP40Wg"
    }
  ],
  "presence_count": 1
}

Guild Member Object

Guild Member Structure
FieldTypeDescription
user?user objectthe user this guild member represents
nick??stringthis user’s guild nickname
avatar??stringthe member’s guild avatar hash
banner??stringthe member’s guild banner hash
rolesarray of snowflakesarray of role object ids
joined_at?ISO8601 timestampwhen the user joined the guild
premium_since??ISO8601 timestampwhen the user started boosting the guild
deafbooleanwhether the user is deafened in voice channels
mutebooleanwhether the user is muted in voice channels
flagsintegerguild member flags represented as a bit set, defaults to 0
pending?booleanwhether the user has not yet passed the guild’s Membership Screening requirements
permissions?stringtotal permissions of the member in the channel, including overwrites, returned when in the interaction object
communication_disabled_until??ISO8601 timestampwhen 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 objectdata 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
{
  "user": {},
  "nick": "NOT API SUPPORT",
  "avatar": null,
  "banner": null,
  "roles": [],
  "joined_at": "2015-04-26T06:26:56.936000+00:00",
  "deaf": false,
  "mute": false
}
Guild Member Flags
FlagValueDescriptionEditable
DID_REJOIN1 << 0Member has left and rejoined the guildfalse
COMPLETED_ONBOARDING1 << 1Member has completed onboardingfalse
BYPASSES_VERIFICATION1 << 2Member is exempt from guild verification requirementstrue
STARTED_ONBOARDING1 << 3Member has started onboardingfalse
IS_GUEST1 << 4Member is a guest and can only access the voice channel they were invited tofalse
STARTED_HOME_ACTIONS1 << 5Member has started Server Guide new member actionsfalse
COMPLETED_HOME_ACTIONS1 << 6Member has completed Server Guide new member actionsfalse
AUTOMOD_QUARANTINED_USERNAME1 << 7Member’s username, display name, or nickname is blocked by AutoModfalse
DM_SETTINGS_UPSELL_ACKNOWLEDGED1 << 9Member has dismissed the DM settings upsellfalse
AUTOMOD_QUARANTINED_GUILD_TAG1 << 10Member’s guild tag is blocked by AutoModfalse
BYPASSES_VERIFICATION allows a member who does not meet verification requirements to participate in a server.

Integration Object

Integration Structure
FieldTypeDescription
idsnowflakeintegration id
namestringintegration name
typestringintegration type (twitch, youtube, discord, or guild_subscription)
enabledbooleanis this integration enabled
syncing? *booleanis this integration syncing
role_id? *snowflakeid that this integration uses for “subscribers”
enable_emoticons? *booleanwhether emoticons should be synced for this integration (twitch only currently)
expire_behavior? *integration expire behaviorthe behavior of expiring subscribers
expire_grace_period? *integerthe grace period (in days) before expiring subscribers
user?user objectuser for this integration
accountaccount objectintegration account information
synced_at? *ISO8601 timestampwhen this integration was last synced
subscriber_count? *integerhow many subscribers this integration has
revoked? *booleanhas this integration been revoked
application?application objectThe bot/OAuth2 application for discord integrations
scopes?array of OAuth2 scopesthe scopes the application has been authorized for
* These fields are not provided for discord bot integrations.
Some older integrations may not have an attached user.
Integration Expire Behaviors
ValueName
0Remove role
1Kick

Integration Account Object

Integration Account Structure
FieldTypeDescription
idstringid of the account
namestringname of the account

Integration Application Object

Integration Application Structure
FieldTypeDescription
idsnowflakethe id of the app
namestringthe name of the app
icon?stringthe icon hash of the app
descriptionstringthe description of the app
bot?user objectthe bot associated with this application

Ban Object

Ban Structure
FieldTypeDescription
reason?stringthe reason for the ban
useruser objectthe banned user
Example Ban
{
  "reason": "mentioning b1nzy",
  "user": {
    "username": "Mason",
    "discriminator": "9999",
    "id": "53908099506183680",
    "avatar": "a_bab14f271d565501444b2ca3be944b25",
    "public_flags": 131141
  }
}

Welcome Screen Object

Welcome Screen Structure
FieldTypeDescription
description?stringthe server description shown in the welcome screen
welcome_channelsarray of welcome screen channel objectsthe channels shown in the welcome screen, up to 5
Welcome Screen Channel Structure
FieldTypeDescription
channel_idsnowflakethe channel’s id
descriptionstringthe description shown for the channel
emoji_id?snowflakethe emoji id, if the emoji is custom
emoji_name?stringthe emoji name if custom, the unicode character if standard, or null if no emoji is set
Example Welcome Screen
{
  "description": "Discord Developers is a place to learn about Discord's API, bots, and SDKs and integrations. This is NOT a general Discord support server.",
  "welcome_channels": [
    {
      "channel_id": "697138785317814292",
      "description": "Follow for official Discord API updates",
      "emoji_id": null,
      "emoji_name": "📡"
    },
    {
      "channel_id": "697236247739105340",
      "description": "Get help with Bot Verifications",
      "emoji_id": null,
      "emoji_name": "📸"
    },
    {
      "channel_id": "697489244649816084",
      "description": "Create amazing things with Discord's API",
      "emoji_id": null,
      "emoji_name": "🔬"
    },
    {
      "channel_id": "613425918748131338",
      "description": "Integrate Discord into your game",
      "emoji_id": null,
      "emoji_name": "🎮"
    },
    {
      "channel_id": "646517734150242346",
      "description": "Find more places to help you on your quest",
      "emoji_id": null,
      "emoji_name": "🔦"
    }
  ]
}

Guild Onboarding Object

Represents the onboarding flow for a guild.
Guild Onboarding Structure
FieldTypeDescription
guild_idsnowflakeID of the guild this onboarding is part of
promptsarray of onboarding prompt objectsPrompts shown during onboarding and in customize community
default_channel_idsarray of snowflakesChannel IDs that members get opted into automatically
enabledbooleanWhether onboarding is enabled in the guild
modeonboarding modeCurrent mode of onboarding
Onboarding Prompt Structure
FieldTypeDescription
idsnowflakeID of the prompt
typeprompt typeType of prompt
optionsarray of prompt option objectsOptions available within the prompt
titlestringTitle of the prompt
single_selectbooleanIndicates whether users are limited to selecting one option for the prompt
requiredbooleanIndicates whether the prompt is required before a user completes the onboarding flow
in_onboardingbooleanIndicates whether the prompt is present in the onboarding flow. If false, the prompt will only appear in the Channels & Roles tab
Prompt Option Structure
FieldTypeDescription
idsnowflakeID of the prompt option
channel_idsarray of snowflakesIDs for channels a member is added to when the option is selected
role_idsarray of snowflakesIDs for roles assigned to a member when the option is selected
emoji?emoji objectEmoji of the option (see below)
emoji_id?snowflakeEmoji ID of the option (see below)
emoji_name?stringEmoji name of the option (see below)
emoji_animated?booleanWhether the emoji is animated (see below)
titlestringTitle of the option
description?stringDescription 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.
NameValueDescription
ONBOARDING_DEFAULT0Counts only Default Channels towards constraints
ONBOARDING_ADVANCED1Counts Default Channels and Questions towards constraints
Prompt Types
NameValue
MULTIPLE_CHOICE0
DROPDOWN1
Example Guild Onboarding
{
  "guild_id": "960007075288915998",
  "prompts": [
    {
      "id": "1067461047608422473",
      "title": "What do you want to do in this community?",
      "options": [
        {
          "id": "1067461047608422476",
          "title": "Chat with Friends",
          "description": "",
          "emoji": {
            "id": "1070002302032826408",
            "name": "chat",
            "animated": false
          },
          "role_ids": [],
          "channel_ids": [
            "962007075288916001"
          ]
        },
        {
          "id": "1070004843541954678",
          "title": "Get Gud",
          "description": "We have excellent teachers!",
          "emoji": {
            "id": null,
            "name": "😀",
            "animated": false
          },
          "role_ids": [
            "982014491980083211"
          ],
          "channel_ids": []
        }
      ],
      "single_select": false,
      "required": false,
      "in_onboarding": true,
      "type": 0
    }
  ],
  "default_channel_ids": [
    "998678771706110023",
    "998678693058719784",
    "1070008122577518632",
    "998678764340912138",
    "998678704446263309",
    "998678683592171602",
    "998678699715067986"
  ],
  "enabled": true
}

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, and pending 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
FieldTypeDescription
invites_disabled_until?ISO8601 timestampwhen invites get enabled again
dms_disabled_until?ISO8601 timestampwhen direct messages get enabled again
dm_spam_detected_at??ISO8601 timestampwhen the dm spam was detected
raid_detected_at??ISO8601 timestampwhen the raid was detected
Example Incidents Data
{
  "invites_disabled_until": "2023-09-01T14:48:02.222000+00:00",
  "dms_disabled_until": null
}

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
FieldTypeDescriptionRequiredDefault
with_counts?booleanwhen true, will return approximate member and presence counts for the guildfalsefalse
Example Response
{
  "id": "2909267986263572999",
  "name": "Mason's Test Server",
  "icon": "389030ec9db118cb5b85a732333b7c98",
  "description": null,
  "splash": "75610b05a0dd09ec2c3c7df9f6975ea0",
  "discovery_splash": null,
  "approximate_member_count": 2,
  "approximate_presence_count": 2,
  "features": [
    "INVITE_SPLASH",
    "VANITY_URL",
    "COMMERCE",
    "BANNER",
    "NEWS",
    "VERIFIED",
    "VIP_REGIONS"
  ],
  "emojis": [
    {
      "name": "ultrafastparrot",
      "roles": [],
      "id": "393564762228785161",
      "require_colons": true,
      "managed": false,
      "animated": true,
      "available": true
    }
  ],
  "banner": "5c3cb8d1bc159937fffe7e641ec96ca7",
  "owner_id": "53908232506183680",
  "application_id": null,
  "region": null,
  "afk_channel_id": null,
  "afk_timeout": 300,
  "system_channel_id": null,
  "widget_enabled": true,
  "widget_channel_id": "639513352485470208",
  "verification_level": 0,
  "roles": [
    {
      "id": "2909267986263572999",
      "name": "@everyone",
      "permissions": "49794752",
      "position": 0,
      "color": 0,
      "colors": {
        "primary_color": 0,
        "secondary_color": null,
        "tertiary_color": null
      },
      "hoist": false,
      "managed": false,
      "mentionable": false
    }
  ],
  "default_message_notifications": 1,
  "mfa_level": 0,
  "explicit_content_filter": 0,
  "max_presences": null,
  "max_members": 250000,
  "max_video_channel_users": 25,
  "vanity_url_code": "no",
  "premium_tier": 0,
  "premium_subscription_count": 0,
  "system_channel_flags": 0,
  "preferred_locale": "en-US",
  "rules_channel_id": null,
  "public_updates_channel_id": null,
  "safety_alerts_channel_id": null
}

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
FieldTypeDescription
namestringguild name
region?stringguild voice region id (deprecated)
verification_level?integerverification level
default_message_notifications?integerdefault message notification level
explicit_content_filter?integerexplicit content filter level
afk_channel_id?snowflakeid for afk channel
afk_timeoutintegerafk timeout in seconds, can be set to: 60, 300, 900, 1800, 3600
icon?image database64 1024x1024 png/jpeg/gif image for the guild icon (can be animated gif when the server has the ANIMATED_ICON feature)
splash?image database64 16:9 png/jpeg image for the guild splash (when the server has the INVITE_SPLASH feature)
discovery_splash?image database64 16:9 png/jpeg image for the guild discovery splash (when the server has the DISCOVERABLE feature)
banner?image database64 16:9 png/jpeg image for the guild banner (when the server has the BANNER feature; can be animated gif when the server has the ANIMATED_BANNER feature)
system_channel_id?snowflakethe id of the channel where guild notices such as welcome messages and boost events are posted
system_channel_flagsintegersystem channel flags
rules_channel_id?snowflakethe id of the channel where Community guilds display rules and/or guidelines
public_updates_channel_id?snowflakethe id of the channel where admins and moderators of Community guilds receive notices from Discord
preferred_locale?stringthe preferred locale of a Community guild used in server discovery and notices from Discord; defaults to “en-US”
featuresarray of guild feature stringsenabled guild features
description?stringthe description for the guild
premium_progress_bar_enabledbooleanwhether the guild’s boost progress bar should be enabled
safety_alerts_channel_id?snowflakethe 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 name
This endpoint supports the X-Audit-Log-Reason header.
JSON Params
FieldTypeDescriptionChannel Type
namestringchannel name (1-100 characters)All
typeintegerthe type of channelAll
topicstringchannel topic (0-1024 characters)Text, Announcement, Forum, Media
bitrate*integerthe bitrate (in bits) of the voice or stage channel; min 8000Voice, Stage
user_limitintegerthe user limit of the voice channelVoice, Stage
rate_limit_per_userintegeramount of seconds a user has to wait before sending another message (0-21600); bots, as well as users with the permission manage_messages or manage_channel, are unaffectedText, Voice, Stage, Forum, Media
positionintegersorting position of the channel (channels with the same position are sorted by id)All
permission_overwrites**array of partial overwrite objectsthe channel’s permission overwritesAll
parent_idsnowflakeid of the parent category for a channelText, Voice, Announcement, Stage, Forum, Media
nsfwbooleanwhether the channel is nsfwText, Voice, Announcement, Stage, Forum
rtc_regionstringchannel voice region id of the voice or stage channel, automatic when set to nullVoice, Stage
video_quality_modeintegerthe camera video quality mode of the voice channelVoice, Stage
default_auto_archive_durationintegerthe 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 activityText, Announcement, Forum, Media
default_reaction_emojidefault reaction objectemoji to show in the add reaction button on a thread in a GUILD_FORUM or a GUILD_MEDIA channelForum, Media
available_tagsarray of tag objectsset of tags that can be used in a GUILD_FORUM or a GUILD_MEDIA channelForum, Media
default_sort_orderintegerthe default sort order type used to order posts in GUILD_FORUM and GUILD_MEDIA channelsForum, Media
default_forum_layoutintegerthe default forum layout view used to display posts in GUILD_FORUM channelsForum
default_thread_rate_limit_per_userintegerthe initial rate_limit_per_user to 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
* For voice channels, normal servers can set bitrate up to 96000, servers with Boost level 1 can set up to 128000, servers with Boost level 2 can set up to 256000, and servers with Boost level 3 or the 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.
This endpoint takes a JSON array of parameters in the following format:
JSON Params
FieldTypeDescription
idsnowflakechannel id
position??integersorting position of the channel (channels with the same position are sorted by id)
lock_permissions??booleansyncs the permission overwrites with the new parent, if moving to a new category
parent_id??snowflakethe 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
FieldTypeDescription
threadsarray of channel objectsthe active threads
membersarray of thread members objectsa 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
FieldTypeDescriptionDefault
limitintegermax number of members to return (1-1000)1
aftersnowflakethe highest user id in the previous page0

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 optional
Query String Params
FieldTypeDescriptionDefault
querystringQuery string to match username(s) and nickname(s) against.
limitintegermax 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
FieldTypeDescriptionPermission
access_tokenstringan oauth2 access token granted with the guilds.join to the bot’s application for the user you want to add to the guild
nickstringvalue to set user’s nickname toMANAGE_NICKNAMES
rolesarray of snowflakesarray of role ids the member is assignedMANAGE_ROLES
mutebooleanwhether the user is muted in voice channelsMUTE_MEMBERS
deafbooleanwhether the user is deafened in voice channelsDEAFEN_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
FieldTypeDescriptionPermission
nickstringvalue to set user’s nickname toMANAGE_NICKNAMES
rolesarray of snowflakesarray of role ids the member is assignedMANAGE_ROLES
mutebooleanwhether the user is muted in voice channels. Will throw a 400 error if the user is not in a voice channelMUTE_MEMBERS
deafbooleanwhether the user is deafened in voice channels. Will throw a 400 error if the user is not in a voice channelDEAFEN_MEMBERS
channel_idsnowflakeid of channel to move user to (if they are connected to voice)MOVE_MEMBERS
communication_disabled_untilISO8601 timestampwhen 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 guildMODERATE_MEMBERS
flagsintegerguild member flagsMANAGE_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
FieldTypeDescriptionPermission
nick??stringvalue to set user’s nickname toCHANGE_NICKNAME
banner??stringdata URI base64 encoded banner image
avatar??stringdata URI base64 encoded avatar image
bio??stringguild member bio

Modify Current User Nick

PATCH/guilds/{guild.id}/members/@me/nick
Deprecated in favor of Modify Current Member.
Modifies the nickname of the current user in a guild. Returns a 200 with the nickname on success. Fires a Guild Member Update Gateway event.
This endpoint supports the X-Audit-Log-Reason header.
JSON Params
FieldTypeDescriptionPermission
nick??stringvalue to set user’s nickname toCHANGE_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
FieldTypeDescriptionDefault
limit?numbernumber of users to return (up to maximum 1000)1000
before? *snowflakeconsider only users before given user idnull
after? *snowflakeconsider only users after given user idnull
* Provide a user id to 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
FieldTypeDescriptionDefault
delete_message_days?integernumber of days to delete messages for (0-7) (deprecated)0
delete_message_seconds?integernumber 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
FieldTypeDescriptionDefault
user_idsarray of snowflakeslist of user ids to ban (max 200)
delete_message_seconds?integernumber 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.
FieldTypeDescription
banned_usersarray of snowflakeslist of user ids, that were successfully banned
failed_usersarray of snowflakeslist 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
FieldTypeDescriptionDefault
namestringname of the role, max 100 characters”new role”
permissionsstringbitwise value of the enabled/disabled permissions@everyone permissions in guild
color*integerDeprecated RGB color value0
colorsrole colors objectthe role’s colorsdefault role colors object
hoistbooleanwhether the role should be displayed separately in the sidebarfalse
icon?image datathe role’s icon image (if the guild has the ROLE_ICONS feature)null
unicode_emoji?stringthe role’s unicode emoji as a standard emoji (if the guild has the ROLE_ICONS feature)null
mentionablebooleanwhether the role should be mentionablefalse
* 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.
This endpoint takes a JSON array of parameters in the following format:
JSON Params
FieldTypeDescription
idsnowflakerole
position??integersorting 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
FieldTypeDescription
namestringname of the role, max 100 characters
permissionsstringbitwise value of the enabled/disabled permissions
color*integerDeprecated RGB color value
colorsrole colors objectthe role’s colors
hoistbooleanwhether the role should be displayed separately in the sidebar
iconimage datathe role’s icon image (if the guild has the ROLE_ICONS feature)
unicode_emojistringthe role’s unicode emoji as a standard emoji (if the guild has the ROLE_ICONS feature)
mentionablebooleanwhether 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
FieldTypeDescriptionDefault
daysintegernumber of days to count prune for (1-30)7
include_rolesstring; comma-delimited array of snowflakesrole(s) to includenone

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
FieldTypeDescriptionDefault
daysintegernumber of days to prune (1-30)7
compute_prune_countbooleanwhether pruned is returned, discouraged for large guildstrue
include_rolesarray of snowflakesrole(s) to includenone
reason?stringreason 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
{
  "code": "abc",
  "uses": 12
}

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
FieldTypeDescriptionDefault
stylestringstyle of the widget image returned (see below)shield
Widget Style Options
ValueDescriptionExample
shieldshield style widget with Discord icon and guild members online countExample
banner1large image with guild icon, name and online count. “POWERED BY DISCORD” as the footer of the widgetExample
banner2smaller widget style with guild icon, name and online count. Split on the right with Discord logoExample
banner3large image with guild icon, name and online count. In the footer, Discord logo on the left and “Chat Now” on the rightExample
banner4large 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 bottomExample

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
FieldTypeDescription
enabledbooleanwhether the welcome screen is enabled
welcome_channelsarray of welcome screen channel objectschannels linked in the welcome screen and their display options
descriptionstringthe 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
FieldTypeDescription
promptsarray of onboarding prompt objectsPrompts shown during onboarding and in customize community
default_channel_idsarray of snowflakesChannel IDs that members get opted into automatically
enabledbooleanWhether onboarding is enabled in the guild
modeonboarding modeCurrent 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.
FieldTypeDescription
invites_disabled_until??ISO8601 timestamp *when invites will be enabled again
dms_disabled_until??ISO8601 timestamp *when direct messages will be enabled again
* Supplying null disables the action.