From e51f165a870f78e6ea4eec107169a54304dc6632 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Spie=C3=9F?= Date: Sun, 17 Mar 2024 21:18:04 +0100 Subject: [PATCH 1/4] Document bulk ban endpoint --- docs/resources/Guild.md | 26 +++++++++++++++++++++++++ docs/topics/Opcodes_and_Status_Codes.md | 1 + 2 files changed, 27 insertions(+) diff --git a/docs/resources/Guild.md b/docs/resources/Guild.md index a2e98c637f..0b44ac5433 100644 --- 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 `BAN_MEMBERS` permission. Returns 200 response on success, including a field `banned_users` with the IDs of the banned users and `failed_users` with all that were not be banned. The list of `failed_users` will also include all users that 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 index 2ce984862c..5d09535161 100644 --- 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 From 9116b18a47a52bb1231b5dabd767c36cb55f3e03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Spie=C3=9F?= Date: Sun, 17 Mar 2024 21:34:12 +0100 Subject: [PATCH 2/4] Add manage guild permission requirement Co-authored-by: advaith --- docs/resources/Guild.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources/Guild.md b/docs/resources/Guild.md index 0b44ac5433..472ecb4c10 100644 --- a/docs/resources/Guild.md +++ b/docs/resources/Guild.md @@ -1084,7 +1084,7 @@ Remove the ban for a user. Requires the `BAN_MEMBERS` permissions. Returns a 204 ## 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 `BAN_MEMBERS` permission. Returns 200 response on success, including a field `banned_users` with the IDs of the banned users and `failed_users` with all that were not be banned. The list of `failed_users` will also include all users that were already banned. +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 200 response on success, including a field `banned_users` with the IDs of the banned users and `failed_users` with all that were not be banned. The list of `failed_users` will also include all users that were already banned. > info > This endpoint supports the `X-Audit-Log-Reason` header. From 16cfec52fd79bb8ff6ea03f1e149b8a47bbf11cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Spie=C3=9F?= Date: Mon, 18 Mar 2024 18:39:57 +0100 Subject: [PATCH 3/4] Update docs/resources/Guild.md Co-authored-by: Adrian Paschkowski --- docs/resources/Guild.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources/Guild.md b/docs/resources/Guild.md index 472ecb4c10..8fb46f4a06 100644 --- a/docs/resources/Guild.md +++ b/docs/resources/Guild.md @@ -1084,7 +1084,7 @@ Remove the ban for a user. Requires the `BAN_MEMBERS` permissions. Returns a 204 ## 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 200 response on success, including a field `banned_users` with the IDs of the banned users and `failed_users` with all that were not be banned. The list of `failed_users` will also include all users that were already banned. +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. From f866959006f832d0aad2b90ce8cb0b941e9c31f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Spie=C3=9F?= Date: Mon, 18 Mar 2024 22:13:51 +0100 Subject: [PATCH 4/4] Fix nullability --- docs/resources/Guild.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/resources/Guild.md b/docs/resources/Guild.md index 8fb46f4a06..a601deefa7 100644 --- a/docs/resources/Guild.md +++ b/docs/resources/Guild.md @@ -1100,10 +1100,10 @@ Ban up to 200 users from a guild, and optionally delete previous messages sent b 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 | +| 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.