Guild Resource

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
FieldTypeDescription
idsnowflakeguild id
namestringguild name (2-100 characters)
iconstringicon hash
splashstringsplash hash
owner_idsnowflakeid of owner
regionstring{voice_region.id}
afk_channel_idsnowflakeid of afk channel
afk_timeoutintegerafk timeout in seconds
embed_enabledboolis this guild embeddable (e.g. widget)
embed_channel_idsnowflakeid of embedded channel
verification_levelintegerlevel of verification required for the guild
default_message_notificationsintegerdefault message notifications level
explicit_content_filterintegerdefault explicit content filter level
rolesarray of role objectsroles in the guild
emojisarray of emoji objectscustom guild emojis
featuresarray of stringsenabled guild features
mfa_levelintegerrequired MFA level for the guild
application_id?snowflakeapplication id of the guild creator if it is bot-created
widget_enabledboolwhether or not the server widget is enabled
widget_channel_idsnowflakethe channel id for the server widget
joined_at *ISO8601 timestampwhen this guild was joined at
large *boolwhether this is considered a large guild
unavailable *boolis this guild unavailable
member_count *integertotal number of members in this guild
voice_states *array of partial voice state objects(without the guild_id key)
members *array of guild member objectsusers in the guild
channels *array of channel objectschannels in the guild
presences *array of partial presence update objectspresences of the users in the guild
* These fields are only sent within the GUILD_CREATE event
Default Message Notification Level
KeyValue
ALL_MESSAGES0
ONLY_MENTIONS1
Explicit Content Filter Level
LevelInteger
DISABLED0
MEMBERS_WITHOUT_ROLES1
ALL_MEMBERS2
MFA Level
LevelInteger
NONE0
ELEVATED1
Verification Level
LevelIntegerDescription
NONE0unrestricted
LOW1must have verified email on account
MEDIUM2must be registered on Discord for longer than 5 minutes
HIGH3(╯°□°)╯︵ ┻━┻ - must be a member of the server for longer than 10 minutes
VERY_HIGH4┻━┻ミヽ(ಠ益ಠ)ノ彡┻━┻ - must have a verified phone number
Example Guild
{
    "id": "41771983423143937",
    "application_id": null,
    "name": "Discord Developers",
    "icon": "SEkgTU9NIElUUyBBTkRSRUkhISEhISEh",
    "splash": null,
    "owner_id": "80351110224678912",
    "region": "us-east",
    "afk_channel_id": "42072017402331136",
    "afk_timeout": 300,
    "embed_enabled": true,
    "embed_channel_id": "41771983444115456",
    "verification_level": 1,
    "default_message_notifications": 0,
    "explicit_content_filter": 0,
    "mfa_level": 0,
    "widget_enabled": false,
    "widget_channel_id": "41771983423143937",
    "roles": [],
    "emojis": [],
    "features": ["INVITE_SPLASH"],
    "unavailable": false
}

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 Embed Object

Guild Embed Structure
FieldTypeDescription
enabledboolif the embed is enabled
channel_idsnowflakethe embed channel id
Example Guild Embed
{
    "enabled": true,
    "channel_id": "41771983444115456"
}

Guild Member Object

Guild Member Structure
FieldTypeDescription
userobjectuser object
nick?stringthis users guild nickname (if one is set)
rolesarray of snowflakesarray of role object ids
joined_atISO8601 timestampwhen the user joined the guild
deafboolif the user is deafened
muteboolif the user is muted
Example Guild Member
{
    "user": {},
    "nick": "NOT API SUPPORT",
    "roles": [],
    "joined_at": "2015-04-26T06:26:56.936000+00:00",
    "deaf": false,
    "mute": false
}

Integration Object

Integration Structure
FieldTypeDescription
idsnowflakeintegration id
namestringintegration name
typestringintegration type (twitch, youtube, etc)
enabledboolis this integration enabled
syncingboolis this integration syncing
role_idsnowflakeid that this integration uses for "subscribers"
expire_behaviorintegerthe behavior of expiring subscribers
expire_grace_periodintegerthe grace period before expiring subscribers
useruser objectuser for this integration
accountaccount objectintegration account information
synced_atISO8601 timestampwhen this integration was last synced

Integration Account Object

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

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

Create Guild

POST/guilds
Create a new guild. Returns a guild object on success. Fires a Guild Create Gateway event.
By default this endpoint is limited to 10 active guilds. These limits are raised for whitelisted GameBridge applications. Creating channel categories from this endpoint is also not supported.
JSON Params
FieldTypeDescription
namestringname of the guild (2-100 characters)
regionstring{voice_region.id} for voice
iconstringbase64 128x128 jpeg image for the guild icon
verification_levelintegerguild verification level
default_message_notificationsintegerdefault message notifications setting
rolesarray of role objectsnew guild roles
channelsarray of partial channel objectsnew guild's channels
When using the roles parameter, the first member of the array is used to change properties of the guild's @everyone role. If you are trying to bootstrap a guild with additional roles, keep this in mind.
Example Partial Channel Object
{
    "name": "naming-things-is-hard",
    "type": 0
}
If roles are specified, the required id field within each role object is an integer placeholder, and will be replaced by the API upon consumption. Its purpose is to allow you to overwrite a role's permissions in a channel when also passing in channels with the channels array.

Get Guild

GET/guilds/{guild.id}
Returns the guild object for the given id.

Modify Guild

PATCH/guilds/{guild.id}
Modify a guild's settings. Returns the updated guild object on success. Fires a Guild Update Gateway event.
All parameters to this endpoint are optional
JSON Params
FieldTypeDescription
namestringguild name
regionstringguild {voice_region.id}
verification_levelintegerguild verification level
default_message_notificationsintegerdefault message notifications setting
afk_channel_idsnowflakeid for afk channel
afk_timeoutintegerafk timeout in seconds
iconstringbase64 128x128 jpeg image for the guild icon
owner_idsnowflakeuser id to transfer guild ownership to (must be owner)
splashstringbase64 128x128 jpeg image for the guild splash (VIP only)

Delete Guild

DELETE/guilds/{guild.id}
Delete a guild permanently. User must be owner. Returns 204 No Content on success. Fires a Guild Delete Gateway event.

Get Guild Channels

GET/guilds/{guild.id}/channels
Returns a list of guild channel objects.

Create Guild Channel

POST/guilds/{guild.id}/channels
Create a new channel object for the guild. Requires the 'MANAGE_CHANNELS' permission. Returns the new channel object on success. Fires a Channel Create Gateway event.
All parameters for this endpoint are optional excluding 'name'
JSON Params
FieldTypeDescription
namestringchannel name (2-100 characters)
typeintegerthe type of channel
bitrateintegerthe bitrate (in bits) of the voice channel (voice only)
user_limitintegerthe user limit of the voice channel (voice only)
permission_overwritesan array of overwrite objectsthe channel's permission overwrites
parent_idsnowflakeid of the parent category for a channel
nsfwboolif the channel is nsfw

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, with the minimum being a swap between at least two channels.
This endpoint takes a JSON array of parameters in the following format:
JSON Params
FieldTypeDescription
idsnowflakechannel id
positionintegersorting position of the channel

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

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. Fires a Guild Member Add Gateway event. Requires the bot to have the CREATE_INSTANT_INVITE permission.
All parameters to this endpoint except for access_token are optional.
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 users nickname toMANAGE_NICKNAMES
rolesarray of snowflakesarray of role ids the member is assignedMANAGE_ROLES
muteboolif the user is mutedMUTE_MEMBERS
deafboolif the user is deafenedDEAFEN_MEMBERS

Modify Guild Member

PATCH/guilds/{guild.id}/members/{user.id}
Modify attributes of a guild member. Returns a 204 empty response on success. Fires a Guild Member Update Gateway event.
All parameters to this endpoint are optional. When moving members to channels, the API user must have permissions to both connect to the channel and have the MOVE_MEMBERS permission.
JSON Params
FieldTypeDescriptionPermission
nickstringvalue to set users nickname toMANAGE_NICKNAMES
rolesarray of snowflakesarray of role ids the member is assignedMANAGE_ROLES
muteboolif the user is mutedMUTE_MEMBERS
deafboolif the user is deafenedDEAFEN_MEMBERS
channel_idsnowflakeid of channel to move user to (if they are connected to voice)MOVE_MEMBERS

Modify Current User's Nick

PATCH/guilds/{guild.id}/members/@me/nick
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.
JSON Params
FieldTypeDescriptionPermission
nickstringvalue to set users 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.

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.

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.

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.

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.
Query String Params
FieldTypeDescription
delete-message-daysintegernumber of days to delete messages for (0-7)

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.

Get Guild Roles

GET/guilds/{guild.id}/roles
Returns a list of role objects for the guild. Requires the 'MANAGE_ROLES' permission.

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.
JSON Params
FieldTypeDescriptionDefault
namestringname of the role"new role"
permissionsintegerbitwise of the enabled/disabled permissions@everyone permissions in guild
colorintegerRGB color value0
hoistboolwhether the role should be displayed separately in the sidebarfalse
mentionableboolwhether the role should be mentionablefalse

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 takes a JSON array of parameters in the following format:
JSON Params
FieldTypeDescription
idsnowflakerole
positionintegersorting position of the role

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.
JSON Params
FieldTypeDescription
namestringname of the role
permissionsintegerbitwise of the enabled/disabled permissions
colorintegerRGB color value
hoistboolwhether the role should be displayed separately in the sidebar
mentionableboolwhether the role should be mentionable

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.

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 'KICK_MEMBERS' permission.
Query String Params
FieldTypeDescription
daysintegernumber of days to count prune for (1 or more)

Begin Guild Prune

POST/guilds/{guild.id}/prune
Begin a prune operation. Requires the 'KICK_MEMBERS' permission. Returns an object with one 'pruned' key indicating the number of members that were removed in the prune operation. Fires multiple Guild Member Remove Gateway events.
Query String Params
FieldTypeDescription
daysintegernumber of days to prune (1 or more)

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 (with invite metadata) for the guild. Requires 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.

Create Guild Integration

POST/guilds/{guild.id}/integrations
Attach an integration object from the current user to the guild. Requires the 'MANAGE_GUILD' permission. Returns a 204 empty response on success. Fires a Guild Integrations Update Gateway event.
JSON Params
FieldTypeDescription
typestringthe integration type
idsnowflakethe integration id

Modify Guild Integration

PATCH/guilds/{guild.id}/integrations/{integration.id}
Modify the behavior and settings of a integration object for the guild. Requires the 'MANAGE_GUILD' permission. Returns a 204 empty response on success. Fires a Guild Integrations Update Gateway event.
JSON Params
FieldTypeDescription
expire_behaviorintegerthe behavior when an integration subscription lapses (see the integration object documentation)
expire_grace_periodintegerperiod (in seconds) where the integration will ignore lapsed subscriptions
enable_emoticonsboolwhether emoticons should be synced for this integration (twitch only currently)

Delete Guild Integration

DELETE/guilds/{guild.id}/integrations/{integration.id}
Delete the attached integration object for the guild. Requires the 'MANAGE_GUILD' permission. Returns a 204 empty response on success. Fires a Guild Integrations Update Gateway event.

Sync Guild Integration

POST/guilds/{guild.id}/integrations/{integration.id}/sync
Sync an integration. Requires the 'MANAGE_GUILD' permission. Returns a 204 empty response on success.

Get Guild Embed

GET/guilds/{guild.id}/embed
Returns the guild embed object. Requires the 'MANAGE_GUILD' permission.

Modify Guild Embed

PATCH/guilds/{guild.id}/embed
Modify a guild embed object for the guild. All attributes may be passed in with JSON and modified. Requires the 'MANAGE_GUILD' permission. Returns the updated guild embed object.