Guild Resource - Documentation

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.

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 `null` if 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 (`null` is always returned, apart from the largest of guilds)
max_members?	integer	the maximum number of members for the guild
vanity_url_code	?string	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/guilds` endpoints when `with_counts` is `true`
approximate_presence_count?	integer	approximate 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 object	the welcome screen of a Community guild, shown to new members, returned in an Invite’s guild object
nsfw_level	integer	guild age-restriction 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

* 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

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 Age-Restriction 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

* 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

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

{
  "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 Structure

Field	Type	Description
enabled	boolean	whether the widget is enabled
channel_id	?snowflake	the widget channel id

Example Guild Widget Settings

{
  "enabled": true,
  "channel_id": "41771983444115456"
}

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

{
  "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

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
collectibles?	?collectibles object	data for the member’s collectibles

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

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

* These fields are not provided for discord bot integrations.

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

Field	Type	Description
id	snowflake	the id of the app
name	string	the name of the app
icon	?string	the icon hash of the app
description	string	the description of the app
bot?	user object	the bot associated with this application

Ban Object

Ban Structure

Field	Type	Description
reason	?string	the reason for the ban
user	user object	the 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

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

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

{
  "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

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

{
  "invites_disabled_until": "2023-09-01T14:48:02.222000+00:00",
  "dms_disabled_until": null
}

Get Guild

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

{
  "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

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

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_ICON` feature)
splash	?image data	base64 16:9 png/jpeg image for the guild splash (when the server has the `INVITE_SPLASH` feature)
discovery_splash	?image data	base64 16:9 png/jpeg image for the guild discovery splash (when the server has the `DISCOVERABLE` feature)
banner	?image data	base64 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	?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

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

Create Guild Channel

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

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 per second) 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 `BYPASS_SLOWMODE`, 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 age-restricted	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_FORUM` or a `GUILD_MEDIA` channel	Forum, Media
available_tags	array of tag objects	set of tags that can be used in a `GUILD_FORUM` or a `GUILD_MEDIA` channel	Forum, Media
default_sort_order	integer	the default sort order type used to order posts in `GUILD_FORUM` and `GUILD_MEDIA` channels	Forum, Media
default_forum_layout	integer	the default forum layout view used to display posts in `GUILD_FORUM` channels	Forum
default_thread_rate_limit_per_user	integer	the 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
flags	integer	channel flags combined as a bitfield.	Text, Voice, 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

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

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
flags?	?integer	channel flags combined as a bitfield.

List Active Guild Threads

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

Returns a guild member object for the specified user.

List Guild Members

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

This endpoint requires the GUILD_MEMBERS Privileged Intent.

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

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

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

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.join` to 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

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

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

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

Field	Type	Description	Permission
nick?	?string	value to set user’s nickname to	CHANGE_NICKNAME

Add Guild Member Role

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

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

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

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

* 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

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

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

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

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

Returns a list of role objects for the guild.

Get Guild Role

Returns a role object for the specified role.

Get Guild Role Member Counts

Returns a map of role IDs to the number of members with the role. Does not include the @everyone role.

Example Response

{
  "613425648685547541": 1337,
  "1409696176629878905": 2,
  "697138785317814292": 67
}

Create Guild Role

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_ICONS` feature)	null
unicode_emoji	?string	the role’s unicode emoji as a standard emoji (if the guild has the `ROLE_ICONS` feature)	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

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

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

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_ICONS` feature)
unicode_emoji	string	the role’s unicode emoji as a standard emoji (if the guild has the `ROLE_ICONS` feature)
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 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

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

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 `pruned` is 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

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

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

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

Returns a guild widget settings object. Requires the MANAGE_GUILD permission. 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.

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

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
}

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

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

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

Returns the Onboarding object for the guild.

Modify Guild 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

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

* Supplying null disables the action.

​Guild Object

Guild Structure

Default Message Notification Level

Explicit Content Filter Level

MFA Level

Verification Level

Guild Age-Restriction Level

Premium Tier

System Channel Flags

Guild Features

Mutable Guild Features

Example Guild

​Unavailable Guild Object

Example Unavailable Guild

​Guild Preview Object

Guild Preview Structure

Example Guild Preview

​Guild Widget Settings Object

Guild Widget Settings Structure

Example Guild Widget Settings

​Guild Widget Object

Guild Widget Structure

Example Guild Widget

​Guild Member Object

Guild Member Structure

Example Guild Member

Guild Member Flags

​Integration Object

Integration Structure

Integration Expire Behaviors

​Integration Account Object

Integration Account Structure

​Integration Application Object

Integration Application Structure

​Ban Object

Ban Structure

Example Ban

​Welcome Screen Object

Welcome Screen Structure

Welcome Screen Channel Structure

Example Welcome Screen

​Guild Onboarding Object

Guild Onboarding Structure

Onboarding Prompt Structure

Prompt Option Structure

Onboarding Mode

Prompt Types

Example Guild Onboarding

​Membership Screening Object

​Incidents Data Object

Incidents Data Structure

Example Incidents Data

​Get Guild

Query String Params

Example Response

​Get Guild Preview

​Modify Guild

JSON Params

​Get Guild Channels

​Create Guild Channel

JSON Params

​Modify Guild Channel Positions

JSON Params

​List Active Guild Threads

Response Body

​Get Guild Member

​List Guild Members

Query String Params

​Search Guild Members

Query String Params

​Add Guild Member

JSON Params

​Modify Guild Member

JSON Params

​Modify Current Member

JSON Params

​Modify Current User Nick

JSON Params

​Add Guild Member Role

​Remove Guild Member Role

Guild Object

Unavailable Guild Object

Guild Preview Object

Guild Widget Settings Object

Guild Widget Object

Guild Member Object

Integration Object

Integration Account Object

Integration Application Object

Ban Object

Welcome Screen Object

Guild Onboarding Object

Membership Screening Object

Incidents Data Object

Get Guild

Get Guild Preview

Modify Guild

Get Guild Channels

Create Guild Channel

Modify Guild Channel Positions

List Active Guild Threads

Get Guild Member

List Guild Members

Search Guild Members

Add Guild Member

Modify Guild Member

Modify Current Member

Modify Current User Nick

Add Guild Member Role

Remove Guild Member Role

Remove Guild Member

Get Guild Bans

Get Guild Ban

Create Guild Ban

Remove Guild Ban

Bulk Guild Ban

Get Guild Roles

Get Guild Role

Get Guild Role Member Counts

Create Guild Role

Modify Guild Role Positions

Modify Guild Role

Delete Guild Role

Get Guild Prune Count

Begin Guild Prune

Get Guild Voice Regions

Get Guild Invites

Get Guild Integrations

Delete Guild Integration

Get Guild Widget Settings

Modify Guild Widget

Get Guild Widget

Get Guild Vanity URL

Get Guild Widget Image

Get Guild Welcome Screen

Modify Guild Welcome Screen

Get Guild Onboarding

Modify Guild Onboarding

Modify Guild Incident Actions