Skip to content

Guild moderation

A guild ban keeps one account out of one guild and outlives the membership it removes. This page covers bans. Kicking a member is Remove guild member, and timeouts, server mute and deafen are set through Modify guild member.

All routes are relative to https://tebhos.com/api/v1, require authentication and accept both user sessions and bot tokens. Every route requires BAN_MEMBERS. A caller who is not a member, or lacks the permission, receives 403 FORBIDDEN. Error bodies follow Errors.

TEBHOS has no bulk ban and no member prune operation.

Guild ban object

Field Type Description
user object The banned account: id, username (empty when unknown), discriminator (always 0), global_name, avatar (always null) and bot (always false)
reason ?string The reason given when the ban was created
moderator_id ?snowflake The account that created the ban
banned_at ?ISO8601 timestamp When the ban was created or last replaced
expires_at ?ISO8601 timestamp When a temporary ban ends, or null for a permanent ban

A temporary ban is removed automatically when it expires and is no longer returned. Banning an account that is already banned replaces the existing ban.

{
  "user": {
    "id": "1489002177550843906",
    "username": "spammer",
    "discriminator": 0,
    "global_name": null,
    "avatar": null,
    "bot": false
  },
  "reason": "Advertising",
  "moderator_id": "1489002177550843905",
  "banned_at": "2026-09-14T09:12:44+00:00",
  "expires_at": null
}

While a ban exists, the account cannot join the guild: Accept invite and joining from discovery fail with 403 FORBIDDEN.

List guild bans

GET /guilds/{guild_id}/bans

Returns every guild ban object of the guild in one array, with no pagination. Requires BAN_MEMBERS.

Rate limit: guild:members, 40 per 10 seconds per account and guild (shared with the member reads and member search).

curl https://tebhos.com/api/v1/guilds/1489002177550843904/bans \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN"

Create guild ban

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

Bans an account and returns 204 with no body. Requires BAN_MEMBERS. The account does not need to be a member; banning a non-member prevents a later join. When the account is a member, the caller must outrank it in the role hierarchy, and the member is removed.

Rate limit: guild:member:remove, 20 per 10 seconds per account and guild (shared with kick and unban).

JSON body

Every field is optional; send {} for a permanent ban that deletes no messages.

Field Type Description
reason? ?string The reason stored on the ban and in the audit log
delete_message_seconds? integer Delete the account's messages in the guild from this many seconds back. Rounded up to whole days, at most 7 days
delete_message_days? integer Delete messages from this many days back, at most 7. Used only when delete_message_seconds is absent or 0
ban_duration_seconds? integer Make the ban temporary, lasting this many seconds. Omitted or 0 means permanent

Message deletion runs in the background after the ban is stored.

Status Code Condition
400 BAD_REQUEST user_id is not a snowflake
403 FORBIDDEN BAN_MEMBERS is missing, or the caller does not outrank the member
404 NOT_FOUND No account has that ID, or the target is the caller

Creating a ban records a MEMBER_BAN_ADD audit entry, dispatches Guild Ban Add and, for a member, Guild Member Remove to the guild. The banned account's sessions are removed from the guild. The banned member loses their nickname, roles and guild profile, and an active timeout is not kept.

curl -X PUT https://tebhos.com/api/v1/guilds/1489002177550843904/bans/1489002177550843906 \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Advertising", "delete_message_seconds": 86400, "ban_duration_seconds": 604800}'

Remove guild ban

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

Removes a ban and returns 204 with no body. Requires BAN_MEMBERS. Removing a ban that does not exist also returns 204.

Rate limit: guild:member:remove, 20 per 10 seconds per account and guild.

The operation records a MEMBER_BAN_REMOVE audit entry and dispatches Guild Ban Remove. It does not restore the removed membership, roles or deleted messages; the account can rejoin with an invite.

Timeouts

A timeout stops a member from communicating in the guild until a set time. It is applied and removed with the communication_disabled_until field of Modify guild member, which requires MODERATE_MEMBERS. Communication timeout lists what a timed-out member cannot do.