Document bulk ban endpoint (discord#6720)

* Document bulk ban endpoint * Add manage guild permission requirement Co-authored-by: advaith <advaithj1@gmail.com> * Update docs/resources/Guild.md Co-authored-by: Adrian Paschkowski <adrian.paschkowski@ruhr-uni-bochum.de> * Fix nullability --------- Co-authored-by: advaith <advaithj1@gmail.com> Co-authored-by: Adrian Paschkowski <adrian.paschkowski@ruhr-uni-bochum.de>
Jupith · May 14, 2024 · acd6cbf · acd6cbf
1 parent 2f32ee1
commit acd6cbf
Show file tree

Hide file tree

Showing 2 changed files with 27 additions and 0 deletions.
diff --git a/docs/resources/Guild.md b/docs/resources/Guild.md
@@ -1082,6 +1082,32 @@ Remove the ban for a user. Requires the `BAN_MEMBERS` permissions. Returns a 204
 > info
 > This endpoint supports the `X-Audit-Log-Reason` header.
 
+## Bulk Guild Ban % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/bulk-ban
+
+Ban up to 200 users from a guild, and optionally delete previous messages sent by the banned users. Requires both the `BAN_MEMBERS` and `MANAGE_GUILD` permissions. Returns a 200 response on success, including the fields `banned_users` with the IDs of the banned users and `failed_users` with IDs that could not be banned or were already banned.
+
+> info
+> 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          |
+
+> info
+> If none of the users could be banned, an error response code `500000: Failed to ban users` is returned instead.
+
 ## Get Guild Roles % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/roles
 
 Returns a list of [role](#DOCS_TOPICS_PERMISSIONS/role-object) objects for the guild.

diff --git a/docs/topics/Opcodes_and_Status_Codes.md b/docs/topics/Opcodes_and_Status_Codes.md
@@ -311,6 +311,7 @@ Along with the HTTP error code, our API can also return more detailed error code
 | 240000 | Message blocked by harmful links filter                                                                                       |
 | 350000 | Cannot enable onboarding, requirements are not met                                                                            |
 | 350001 | Cannot update onboarding while below requirements                                                                             |
+| 500000 | Failed to ban users                                                                                                           |
 
 ###### Example JSON Error Response