Guild moderation

A guild ban keeps an account out of a guild until you remove the ban or it expires. Every route on this page needs BAN_MEMBERS. In a guild with an elevated MFA level, everyone except the owner also needs two-factor authentication turned on. A caller without the permission gets 403 MISSING_PERMISSIONS, and one without two-factor authentication gets 400 TWO_FACTOR_REQUIRED.

Guild ban object

A guild ban object describes one ban.

A ban also blocks joins from the account's email address and its last IP address. A join returns 403 USER_BANNED_FROM_GUILD for an account or email match and 403 USER_IP_BANNED_FROM_GUILD for an IP match. Fluxer skips the IP match for an address on the instance's IP ban exemption list. Removing the ban lifts both blocks, and permanently deleting the banned account removes all its guild bans.

Structure

Field	Type	Description
user	partial user object	The banned account
reason¹	?string	The ban reason
moderator_id	snowflake	The account that issued or last replaced the ban, or `0` when an instance admin placed it through the Admin API
banned_at	ISO8601 timestamp	Time the ban was issued or last replaced
expires_at²	?ISO8601 timestamp	Time a temporary ban ends, or null for a permanent ban

¹ The body reason, or the X-Audit-Log-Reason value when the body has none

² Fluxer removes an expired ban and never returns it

Example

{
  "user": {"id": "1489002177550843906", "username": "spammer", "discriminator": "0042"},
  "reason": "Advertising",
  "moderator_id": "1489002177550843905",
  "banned_at": "2026-08-14T09:12:44.000Z",
  "expires_at": null
}

List guild bans

GET/v1/guilds/{guild_id}/bans

Bot

Returns every guild ban object in the guild. The list isn't paginated.

Response

Status	Body	Condition
200	array[guild ban object]	Bans were returned

The rate limit is 40 requests per 10 seconds, on the shared guild:members::guild_id bucket.

Create or replace guild ban

PUT/v1/guilds/{guild_id}/bans/{user_id}

Bot Audit reason

Bans the account and returns 204. Banning an account that is already banned replaces the ban, which can make a permanent ban temporary or extend a temporary one. You can ban an account that isn't a member. To ban a member, your highest role must be above theirs. The owner can ban any member, and nobody can ban the owner.

Fluxer removes a banned member from the guild and its threads and records a MEMBER_BAN_ADD audit entry. Sends Guild Ban Add. The guild gets Guild Member Remove and the banned account gets Guild Delete.

JSON body

The body is optional. A request with no body creates a permanent ban and deletes no messages.

Field	Type	Description
delete_message_seconds?	integer	Age of the target's guild messages to delete, in seconds (0-604800)
delete_message_days?	integer	Same as `delete_message_seconds` in days (0-7), ignored when `delete_message_seconds` is set
reason?	?string	Reason stored on the ban (max 512 characters)
ban_duration_seconds?	integer	Ban duration in seconds (0 or 60-63072000), where 0 is permanent

Response

Status	Body	Condition
204	empty	The ban was created or replaced
400	error response	`INVALID_FORM_BODY` when a body field is out of range
403	error response	`MISSING_PERMISSIONS` when your highest role isn't above the member's, or `CONTENT_BLOCKED` when `reason` is blocked
404	error response	`UNKNOWN_USER` when the account doesn't exist, or `UNKNOWN_MEMBER` when the target is you

The rate limit is 20 requests per 10 seconds, on the guild:member:remove::guild_id bucket.

Remove guild ban

DELETE/v1/guilds/{guild_id}/bans/{user_id}

Bot Audit reason

Removes the ban and returns 204. The account can join again through an invite, and messages deleted by the ban stay deleted. Sends Guild Ban Remove and records a MEMBER_BAN_REMOVE audit entry.

Response

Status	Body	Condition
204	empty	The ban was removed
400	error response	`INVALID_FORM_BODY`, with `USER_IS_NOT_BANNED` on `user_id`

The rate limit is 20 requests per 10 seconds, on the guild:member:remove::guild_id bucket.