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

¹ This limit also applies to stream viewers within the channel. The value is always 50 for premium tiers 0 to 1, 150 for premium tier 2, and 300 + 30 * (premium_subscription_count - 14) for premium tier 3.

² Only included when fetched from the Get Guild endpoint with with_counts set to true.

³ Only included in guild objects returned over the Gateway.

Example Guild

{
  "id": "81384788765712384",
  "name": "Discord API",
  "icon": "a363a84e969bcbe1353eb2fdfb2e50e6",
  "description": null,
  "home_header": null,
  "splash": null,
  "discovery_splash": null,
  "features": [
    "INVITE_SPLASH",
    "VIP_REGIONS",
    "PREVIEW_ENABLED",
    "VANITY_URL",
    "CHANNEL_ICON_EMOJIS_GENERATED",
    "COMMUNITY",
    "NEW_THREAD_PERMISSIONS",
    "WELCOME_SCREEN_ENABLED",
    "NEWS",
    "ANIMATED_ICON",
    "AUTO_MODERATION",
    "MEMBER_VERIFICATION_GATE_ENABLED",
    "THREADS_ENABLED",
    "COMMUNITY_EXP_LARGE_UNGATED",
    "SOUNDBOARD",
    "THREE_DAY_THREAD_ARCHIVE"
  ],
  "emojis": [],
  "stickers": [],
  "banner": null,
  "owner_id": "80088516616269824",
  "application_id": null,
  "region": "deprecated",
  "afk_channel_id": null,
  "afk_timeout": 3600,
  "system_channel_id": "381870553235193857",
  "widget_enabled": true,
  "widget_channel_id": null,
  "verification_level": 3,
  "roles": [
    {
      "id": "81384788765712384",
      "name": "@everyone",
      "description": null,
      "permissions": "110917634608832",
      "position": 0,
      "color": 0,
      "hoist": false,
      "managed": false,
      "mentionable": false,
      "icon": null,
      "unicode_emoji": null,
      "flags": 0
    }
  ],
  "default_message_notifications": 1,
  "mfa_level": 1,
  "explicit_content_filter": 2,
  "max_presences": null,
  "max_members": 500000,
  "max_stage_video_channel_users": 50,
  "max_video_channel_users": 25,
  "vanity_url_code": "discord-api",
  "premium_tier": 1,
  "premium_subscription_count": 5,
  "system_channel_flags": 9,
  "preferred_locale": "en-US",
  "rules_channel_id": "381898062269775883",
  "safety_alerts_channel_id": null,
  "public_updates_channel_id": "650136538264502282",
  "hub_type": null,
  "premium_progress_bar_enabled": false,
  "latest_onboarding_question_id": null,
  "incidents_data": null,
  "nsfw": false,
  "nsfw_level": 0
}

Message Notification Level

Explicit Content Filter Level

MFA Level

Verification Level

NSFW Level

Premium Tier

System Channel Flags

Privacy Level

Hub Type

Guild Features

The available guild features, their functionality, and their requirements is subject to arbitrary change. The following table is a best-effort attempt to document the current state of guild features.

¹ This is now a base feature, and the guild feature has no effect if still present.

Mutable Guild Features

These guild features are mutable, and can be edited with the Modify Guild endpoint.

¹ Modification requires the ADMINISTRATOR permission.

² Guild must also pass all discovery requirements in order to set.

³ Feature is only removable, not settable.

⁴ Guild must have access to conversation summaries (either the SUMMARIES_ENABLED or SUMMARIES_ENABLED_GA feature).

User Guild Object

A partial guild object returned from the Get User Guilds endpoint. Represents a guild the user is a member of.

User Guild Structure

¹ Only included when fetched from the Get User Guilds endpoint with with_counts set to true.

Example User Guild

[
  {
    "id": "80351110224678913",
    "name": "1337 Krew",
    "icon": "8342729096ea3675442027381ff50dfe",
    "banner": "bb42bdc37653b7cf58c4c8cc622e76cb",
    "owner": true,
    "permissions": "36953089",
    "features": ["COMMUNITY", "NEWS", "ANIMATED_ICON", "INVITE_SPLASH", "BANNER", "ROLE_ICONS"],
    "approximate_member_count": 420,
    "approximate_presence_count": 69
  }
]

Guild Preview Object

A partial guild object returned from the Get Guild Preview endpoint.

Guild Preview Structure

Example Guild Preview

{
  "id": "752630786561409076",
  "name": "Elite Creative",
  "icon": "278da1c7740e394657c1179f4782aef1",
  "description": "The largest Fortnite Creative server across the globe. Join a Creative community offering events, 1v1s. and more!",
  "home_header": null,
  "splash": "2b4ae5cdd71038b4880b1b57a6e5dacb",
  "discovery_splash": "9d7ec672b89b320ef7a51e5b6ae453b8",
  "features": [
    "ANIMATED_BANNER",
    "ANIMATED_ICON",
    "AUTO_MODERATION",
    "BANNER",
    "COMMUNITY",
    "DISCOVERABLE",
    "ENABLED_DISCOVERABLE_BEFORE",
    "GUILD_ONBOARDING_EVER_ENABLED",
    "GUILD_WEB_PAGE_VANITY_URL",
    "INVITE_SPLASH",
    "NEWS",
    "PREVIEW_ENABLED",
    "RAID_ALERTS_ENABLED",
    "ROLE_ICONS",
    "VANITY_URL",
    "WELCOME_SCREEN_ENABLED"
  ],
  "approximate_member_count": 155451,
  "approximate_presence_count": 7532,
  "emojis": [],
  "stickers": []
}

Guild Widget Object

An embeddable widget for a guild.

Guild Widget Structure

Guild Widget Channel Structure

Guild Widget Member Structure

Guild Widget Member Activity Structure

Example Guild Widget

{
  "id": "1046920999469330512",
  "name": "Alien Network",
  "instant_invite": "https://discord.com/invite/alien",
  "channels": [
    {
      "id": "1053657210082836620",
      "name": "stage",
      "position": 2
    }
  ],
  "members": [
    {
      "id": "0",
      "username": "Dolfies",
      "discriminator": "0000",
      "avatar": null,
      "status": "dnd",
      "activity": {
        "name": "balls lmao"
      },
      "deaf": false,
      "mute": false,
      "self_deaf": false,
      "self_mute": true,
      "suppress": false,
      "channel_id": "1057241425793798144",
      "avatar_url": "https://cdn.discordapp.com/widget-avatars/zOXeOyhOGqx-bwpzszp-obU-_RFE9xI9HG19HylPyMs/actPlrz4a6Kz4NSBV4jmkd1E4raF_UjDuIXnyCjJgY5DpcbFPZnVS1SvQbRkHbXaVLvKKv7gkZi0PPXX2gdxngxHSyFH7AuxH0Y-8pgQh5xhWQaC9PsmeJ64Bv8xjF9Wb_whrDVNA-I4Eg"
    }
  ],
  "presence_count": 69
}

Guild Widget Settings Structure

Example Guild Widget Settings

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

Guild Member Object

A participating user in a guild.

Guild Member Structure

¹ Won't be included in the member object attached to Message Create and Message Update Gateway events.

² Won't be included in contexts that are impossible for a pending member to exist in. If the guild has previewing disabled, this field will always be false.

³ If the value is a time in the past, the member's timeout has expired and they can communicate again.

⁴ Only returned when received in a slash command interaction.

Guild Member Flags

¹ Allows a member who does not meet verification requirements to participate in the guild, and forces the member's pending status to be false. Removing this flag does not make the member pending again.

² Quarantined users, similar to timed out users, are prevented from interacting with the guild in any way.

Example Guild Member

{
  "avatar": null,
  "banner": null,
  "communication_disabled_until": null,
  "unusual_dm_activity_until": null,
  "flags": 34,
  "joined_at": "2023-03-22T13:59:47.553000+00:00",
  "nick": null,
  "pending": false,
  "premium_since": null,
  "roles": [
    "1040221495437299782",
    "1029330445336313927",
    "1049489484179312691",
    "1053820570367701012",
    "1029317826755956827",
    "1029316630431412287"
  ],
  "user": {
    "id": "828387742575624222",
    "username": "jupppper",
    "avatar": "e14a7c62b0b38068be88be194b23910f",
    "discriminator": "0",
    "public_flags": 16384,
    "banner": "e45c9b5799fcb46b82bd5f1afc1b30c4",
    "global_name": "Jup",
    "accent_color": 1,
    "avatar_decoration_data": null,
    "primary_guild": null
  },
  "mute": false,
  "deaf": false
}

Supplemental Guild Member Object

Additional information about a participating user's join source in a guild.

Supplemental Guild Member Structure

¹ user_id is only included when fetched from the Get Guild Members Supplemental endpoint.

² member is only included when fetched from the Search Guild Members endpoint.

Join Source Type

Example Supplemental Guild Member

{
  "user_id": "257496590401536000",
  "source_invite_code": "41i3n5",
  "join_source_type": 5,
  "inviter_id": "1001086404203389018",
  "integration_type": null
}

Ban Object

A ban for a guild. Banned users can't rejoin a guild unless unbanned.

Ban Structure

Example Ban

{
  "user": {
    "id": "53908232506183680",
    "username": "mason",
    "avatar": "a_d5efa99b3eeaa7dd43acca82f5692432",
    "discriminator": "0",
    "public_flags": 4325445,
    "banner": "42db4e3be824706cb1304fba05995722",
    "accent_color": null,
    "global_name": "Mason",
    "avatar_decoration_data": null,
    "primary_guild": null
  },
  "reason": "mentioning b1nzy"
}

Welcome Screen Object

Welcome Screen Structure

Welcome Screen Channel Structure

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": "🔦"
    }
  ]
}

Member Verification Object

In guilds with member verification enabled, when a member joins, a Guild Member Add Gateway event will be dispatched but they will initially be restricted from doing any actions in the guild, and pending will be true in the guild member object. When the member completes the verification, a Guild Member Update Gateway event will be dispatched and pending will be false.

To represent a member's progress towards becoming a full member of the guild, a Guild Join Request Create Gateway event will be dispatched. Once the join request is approved, the member's pending status will be false and they will be able to interact with the guild. Unless using manual approval, the join request will be automatically approved when the user submits their join request.

Assigning a member the BYPASSES_VERIFICATION flag will force their pending status to be false, regardless of the join request's status.

Guild Previewing

Discoverable guilds and guilds with member verification enabled have the PREVIEW_ENABLED feature by default. This allows the guild to be lurkable by users who are not members, if discoverable, and allows members who have not passed the verification gate to view the guild without interacting with it.

If a guild has member verification enabled and is not previewable, new joiners will not be able to view the guild until they pass the verification gate, and are therefore not considered members until they do. This means that a Guild Member Add Gateway event will not be dispatched until the member has passed the verification gate, and pending will always be false in the guild member object for new joiners. Join requests will continue to be dispatched as normal, but there will not be an associated guild member until the join request is approved.

From the joiner's perspective, they will also not receive a Guild Create Gateway event or any other events dispatched from the guild until they pass member verification. Non-previewable pending guilds can be retrieved with the Get Join Request Guilds endpoint. Their join requests are also sent in the guild_join_requests field of the Ready event.

Manual Approval

To use form field types other than TERMS, the guild must have the MEMBER_VERIFICATION_MANUAL_APPROVAL guild feature enabled. When using these form field types, join requests must be manually approved after they are submitted before the user can complete member verification.

When only using a TERMS form field type, the join request will be automatically approved when the user submits the request.

Member Verification Structure

¹ Only included when fetched from the Get Guild Member Verification endpoint with with_guild set to true.

Member Verification Form Field Structure

¹ Not present when fetched from the Get Guild Member Verification endpoint. For TERMS form fields, the response should be true. For MULTIPLE_CHOICE form field types, the response is the index of the selected choice.

Member Verification Form Field Type

Member Verification Guild Structure

Example Member Verification

{
  "version": "2022-12-21T16:08:17.822000+00:00",
  "form_fields": [
    {
      "field_type": "TERMS",
      "label": "Read and agree to the server rules",
      "description": null,
      "automations": null,
      "required": true,
      "values": [
        "No spam or self-promotion (server invites, advertisements, etc) without permission from a staff member. This includes DMing fellow members.",
        "No age-restricted or obscene content. This includes text, images, or links featuring nudity, sex, hard violence, or other graphically disturbing content.",
        "If you see something against the rules or something that makes you feel unsafe, let staff know. We want this server to be a welcoming space!"
      ]
    },
    {
      "field_type": "TEXT_INPUT",
      "label": "Why do you like aliens?",
      "description": null,
      "automations": null,
      "required": true,
      "placeholder": null
    },
    {
      "field_type": "MULTIPLE_CHOICE",
      "label": "What is your favorite alien movie?",
      "description": null,
      "automations": null,
      "required": true,
      "choices": ["Alien", "E.T."]
    }
  ],
  "description": "Alien",
  "guild": {
    "id": "1046920999469330512",
    "name": "Alien Network",
    "icon": "66b0f4d96c145970fa9d96ada8afadf3",
    "description": "Where the 👽s 👽 and sometimes very 👽 things happen 😨.",
    "home_header": "39ba384a31e9c285649ad00b359946ab",
    "splash": "b40e61f7730b8781b9a551964570e0cc",
    "discovery_splash": "0e11ae8d9f1c86958be05e61b0c90ac3",
    "features": [],
    "approximate_member_count": 100,
    "approximate_presence_count": 99,
    "emojis": [],
    "verification_level": 2
  }
}

Guild Join Request Object

Guild join requests are an extension of member verification that represent a user's request to join a guild. A join request is created when a user attempts to join a guild with member verification enabled, and the user must complete the verification process to join the guild. All join requests are stored for 180 days.

Most join request features require the MEMBER_VERIFICATION_MANUAL_APPROVAL guild feature, as join request are automatically actioned when only using the TERMS form field type and do not require manual approval. This includes most of the join request endpoints, such as Get Guild Join Request and Action Guild Join Request.

Guild Join Request Structure

¹ Only included when fetched from the Get Guild Join Request or Get Guild Join Requests endpoints, or when receiving a related Gateway event as a moderator.

² Only guaranteed for users other than the current user.

Guild Join Request Status

Example Guild Join Request

{
  "created_at": "2024-05-20T03:45:28.965000+00:00",
  "join_request_id": "1241959960003477524",
  "id": "1241959960003477524",
  "rejection_reason": null,
  "application_status": "APPROVED",
  "actioned_at": "2024-05-20T03:45:44.547975+00:00",
  "actioned_by_user": {
    "id": "828387742575624222",
    "username": "jupppper",
    "avatar": "e14a7c62b0b38068be88be194b23910f",
    "discriminator": "0",
    "public_flags": 16384,
    "banner": "e45c9b5799fcb46b82bd5f1afc1b30c4",
    "global_name": "Jup",
    "accent_color": 1,
    "avatar_decoration_data": null,
    "primary_guild": null
  },
  "form_responses": [
    {
      "field_type": "TERMS",
      "label": "Read and agree to the server rules",
      "description": null,
      "automations": null,
      "required": true,
      "values": [
        "No spam or self-promotion (server invites, advertisements, etc) without permission from a staff member. This includes DMing fellow members.",
        "No age-restricted or obscene content. This includes text, images, or links featuring nudity, sex, hard violence, or other graphically disturbing content.",
        "If you see something against the rules or something that makes you feel unsafe, let staff know. We want this server to be a welcoming space!"
      ],
      "response": true
    },
    {
      "field_type": "TEXT_INPUT",
      "label": "Why do you like aliens?",
      "description": null,
      "automations": null,
      "required": true,
      "placeholder": null,
      "response": "I like aliens because they're cool!"
    },
    {
      "field_type": "MULTIPLE_CHOICE",
      "label": "What is your favorite alien movie?",
      "description": null,
      "automations": null,
      "required": true,
      "values": ["Alien", "E.T."],
      "response": 0
    }
  ],
  "last_seen": "2024-05-20T03:45:44.547975+00:00",
  "guild_id": "1046920999469330512",
  "user_id": "852892297661906993",
  "user": {
    "id": "852892297661906993",
    "username": "alien",
    "global_name": "Alien",
    "avatar": "14733482e560d9267c0a414b21b2fb8d",
    "discriminator": "0",
    "public_flags": 64,
    "avatar_decoration_data": null,
    "primary_guild": null
  },
  "interview_channel_id": null
}

Onboarding Object

The onboarding flow for a guild.

Onboarding Structure

Onboarding Mode

Defines the criteria used to satisfy Onboarding constraints that are required for enabling.

Onboarding Prompt Structure

Onboarding Prompt Option Structure

Onboarding Prompt Type

Example 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,
  "mode": 0,
  "below_requirements": false
}

Endpoints

Get User Guilds

Returns a list of user guild objects representing the guilds the current user is a member of.

Query String Params

¹ For OAuth2 requests, this parameter requires the additional guilds.members.read scope.

Get Join Request Guilds

Returns a list of partial guild objects representing guilds without the PREVIEW_ENABLED guild feature the current user has pending join requests for.

Example Response

[
  {
    "id": "80351110224678913",
    "name": "1337 Krew",
    "icon": "8342729096ea3675442027381ff50dfe",
    "description": null,
    "home_header": null,
    "splash": null,
    "discovery_splash": null,
    "features": ["COMMUNITY", "NEWS", "MEMBER_VERIFICATION_GATE_ENABLED", "MEMBER_VERIFICATION_MANUAL_APPROVAL"]
  }
]

Leave Guild

Leaves the given guild ID. Returns a 204 empty response on success. Fires a Guild Delete and a Guild Member Remove Gateway event.

JSON Params

Create Guild

Creates a new guild. Returns a guild object on success. Fires a Guild Create Gateway event.

JSON Params

¹ The first member of the array is used to change properties of the guild's default (@everyone) role. If you are trying to bootstrap a guild with additional roles, keep this in mind. Additionally, 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.

² When specified, none of the default channels are created, and the position field is always ignored. Additionally, the id field within each channel object may be set to an integer placeholder, and will be replaced by the API upon consumption. Its purpose is to allow you to create GUILD_CATEGORY channels by setting the parent_id field on any children to the category's id field. Category channels must be listed before any children.

³ Adds the INTERNAL_EMPLOYEE_ONLY guild feature, making the server only available for Discord employees. Only settable by Discord employees.

Example Partial Channel Object

{
  "name": "my-category",
  "type": 4,
  "id": 1
}

{
  "name": "naming-things-is-hard",
  "type": 0,
  "parent_id": 1
}

Get Guild

Returns a guild object for the given guild ID.

Query String Params

Get Guild Preview

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

Modify Guild

Modifies a guild's settings. Requires the MANAGE_GUILD permission. Returns the updated guild object on success. Fires a Guild Update Gateway event.

JSON Params

¹ Setting these to a value of 1 will implicitly create a new "#rules" or "#moderator-only" channel.

Modify Guild MFA Level

Modifies the guild's MFA requirement for administrative actions within the guild. Requires the MANAGE_GUILD permission. Fires a Guild Update Gateway event.

JSON Params

Response Body

Example Response

{
  "level": 1
}

Delete Guild

Deletes a guild permanently. User must be the owner. Returns a 204 empty response on success. Fires a Guild Delete Gateway event.

Get Guild Members

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

Query String Params

Query Guild Members

Returns a list of guild member objects whose username or nickname contains a provided string. Functionally identical to the Request Guild Members Gateway Opcode.

Query String Params

Search Guild Members

Returns supplemental guild member objects containing guild member objects that match a specified query. Requires the MANAGE_GUILD permission.

This endpoint utilizes Elasticsearch to power results. This means that while it is very powerful, it's also tricky to use and reliant on the index, meaning results may not be immediately available for a recently-joined member.

JSON Params

Member Sort Type

Member Filter Structure

Safety Signals Structure

Query Structure

Range Query Structure

Member Pagination Filter Structure

Response Body

Get Guild Members Supplemental

Returns a list of supplemental guild member objects including join source information for the given user IDs.

JSON Params

Get Guild Member

Returns a guild member object for the specified user.

Join Guild

Adds the current user to the guild. The guild must be discoverable. Returns the guild member object or a 204 empty response (if the user is already a member of the guild) on success. May fire a Guild Create, Guild Member Add, and/or Guild Join Request Create Gateway event.

For guilds with member verification enabled, this endpoint will default to adding new members as pending in the guild member object. Members that are pending will have to complete member verification before they become full members that can talk.

Query String Params

¹ Lurking a guild allows the user to receive Gateway events for the guild without being a full member. This is useful for previewing the guild before joining. Lurking requires the PREVIEW_ENABLED guild feature.

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 the joined guild member object or a 204 empty response (if the user is already a member of the guild) on success. May fire a Guild Member Add and/or Guild Join Request Create Gateway event.

For guilds with member verification and guild previewing enabled, this endpoint will default to adding new members as pending in the guild member object. Members that are pending will have to complete member verification before they become full members that can talk.

JSON Params

¹ For guilds with member verification enabled, assigning the BYPASSES_VERIFICATION guild member flag will add the user as a full member (pending is false in the member object).

Modify Guild Member

Modifies attributes of a guild member. Returns the updated guild member object on success. Fires a Guild Member Update Gateway event.

JSON Params

¹ Requires the member to be connected to voice. When moving members to channels, the current user must have permissions to both connect to the channel and have the MOVE_MEMBERS permission. If the channel_id is set to null, this will force the target user to be disconnected from voice.

² Guild administrators cannot be timed out. If a member is timed out and becomes an administrator before their timeout expires, the timeout will no longer have an effect.

Modify Current Guild Member

Modifies the current user's member in the guild. Returns the updated guild member object on success (including extra bio and banner fields). Fires a Guild Member Update Gateway event.

JSON Params

Modify Current Guild Member Nick

Modifies the current user's member in the guild. Returns the updated guild member object on success (including extra bio and banner fields). Fires a Guild Member Update Gateway event.

See Modify Current Guild Member for more information.

Modify Guild Member Profile

Modifies the current user's profile in the guild. Returns a profile metadata object on success. Fires a Guild Member Update Gateway event.

JSON Params

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.

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.

Remove Guild Member

Removes a member from a guild. Requires the KICK_MEMBERS permission. Returns a 204 empty response on success. Fires a Guild Member Remove Gateway event.

Acknowledge DM Settings Upsell Modal

Adds the DM_SETTINGS_UPSELL_ACKNOWLEDGED member flag to the current user. Returns a 204 empty response on success. Fires a Guild Member Update Gateway event.

Get Guild Bans

Returns a list of ban objects for the guild. Requires the BAN_MEMBERS permission.

Query String Params

¹ Bans will always be returned in ascending order by user ID.

² Ban pagination for user accounts is currently optional. It must be explicitly opted into by specifying the limit query string parameter. Without specifying it, the before and after query string parameters will not work, and all bans will be returned by default. For bots, pagination is always enabled and 1000 bans are returned by default.

Search Guild Bans

Returns a list of ban objects whose username or display name contains a provided string.

Query String Params

Get Guild Ban

Returns a ban object for the given user. Requires the BAN_MEMBERS permission.

Create Guild Ban

Creates a guild ban and optionally deletes previous messages sent by the banned user. Requires the BAN_MEMBERS permission. Returns a 204 empty response on success. Fires Guild Ban Add and optionally Guild Member Remove Gateway events.

JSON Params

Bulk Guild Ban

Create multiple guild bans and optionally delete previous messages sent by the banned users. Requires both the BAN_MEMBERS and MANAGE_GUILD permissions. Fires multiple Guild Ban Add and optionally Guild Member Remove Gateway events.

JSON Params

Response Body

¹ A ban will fail if the user is already banned, the user has a higher role than the current user, the user is the owner of the guild, or the user is the current user. If a bulk ban has no successful bans, the response will be an error.

Delete Guild Ban

Removes the ban for a user. Requires the BAN_MEMBERS permission. Returns a 204 empty response on success. Fires a Guild Ban Remove Gateway event.

Get Guild Roles

Returns a list of role objects for the guild.

Get Guild Role

Returns a role object for the given role.

Get Guild Role Member Counts

Returns a mapping of role IDs to their respective member counts.

Example Response

{
  "1040221495437299782": 2,
  "1040221495437299783": 1,
  "1040221495437299784": 0
}

Get Guild Role Members

Returns a list of member IDs that have the specified role, up to a maximum of 100.

Example Response

["852892297661906993", "907489667895676928"]

Add Guild Role Members

Adds multiple guild members to a role. Requires the MANAGE_ROLES permission. Returns a mapping of member IDs to guild member objects. Fires multiple Guild Member Update Gateway events.

JSON Params

Example Response

{
  "863406480111566858": {
    "avatar": null,
    "banner": null,
    "communication_disabled_until": null,
    "unusual_dm_activity_until": null,
    "flags": 0,
    "joined_at": "2022-10-11T12:31:03.882000+00:00",
    "nick": ":~]",
    "pending": false,
    "premium_since": null,
    "roles": ["1040221495437299782"],
    "user": {
      "id": "863406480111566858",
      "username": "leaduck",
      "global_name": "LeaDuck",
      "avatar": "bb450561133bac3da5c7e201db40af6c",
      "discriminator": "0",
      "public_flags": 256,
      "avatar_decoration_data": null,
      "primary_guild": null
    },
    "mute": false,
    "deaf": false
  }
}

Create Guild Role

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

JSON Params