Moderation

Bots can kick, ban, time out, delete messages in bulk and read the audit log. The server enforces everything; your bot should still check the person who asked.

Rules the server enforces

• The bot needs the matching permission: Kick Members, Ban Members, Timeout Members, Manage Messages, View Audit Logs.
• The target must rank below the bot. The server owner cannot be kicked, banned or timed out.
• A timeout is an end time (timeout, ISO 8601). Members who hold Timeout Members themselves cannot be timed out (IsElevated), and nobody can time out themselves. End a timeout early with remove: ["Timeout"].
• A ban can delete the user's messages from the last 7 days (delete_message_seconds, at most 604800).
• Bulk delete takes up to 100 messages younger than a week.

Rules your bot should add

1. Check the person, not just the bot. Use user_permissions from the interaction (see Roles and permissions).
2. Compare ranks. Refuse when the target ranks at or above the person who asked.
3. Refuse obvious mistakes: acting on yourself, on the bot, or on the owner.
4. Write a reason. Reasons appear in the audit log.
5. Answer privately. Moderation replies are best ephemeral.

Kick, ban, time out

# kick
curl -X DELETE "https://api.zrzur.com/servers/SERVER_ID/members/USER_ID" \
  -H "x-bot-token: YOUR_BOT_TOKEN" -H "X-Audit-Log-Reason: Spam"

# ban
curl -X PUT "https://api.zrzur.com/servers/SERVER_ID/bans/USER_ID" \
  -H "x-bot-token: YOUR_BOT_TOKEN" -H "content-type: application/json" \
  -d '{ "reason": "Spam", "delete_message_seconds": 86400 }'

# time out until a date
curl -X PATCH "https://api.zrzur.com/servers/SERVER_ID/members/USER_ID" \
  -H "x-bot-token: YOUR_BOT_TOKEN" -H "content-type: application/json" \
  -d '{ "timeout": "2026-12-01T12:00:00Z" }'

The header X-Audit-Log-Reason puts a reason in the audit log. It works on every moderation route.

Audit log

GET /servers/{target}/audit_logs lists who did what. Actions done by your bot appear with the bot as the actor.

Reference

DELETE /channels/{target}/messages/bulk

Bulk Delete Messages. Delete multiple messages you've sent or one you have permission to delete. This will always require ManageMessages permission regardless of whether you own the message or not. Messages must have been sent within the past 1 week.

Permissions: Channel:ManageMessages · Rate limit: channels, 15 / 10 s

DELETE /servers/{server_id}/members/{member_id}

Kick Member. Removes a member from the server.

Permissions: Channel:KickMembers · Rate limit: servers, 5 / 10 s

DELETE /servers/{server}/bans/{target}

Unban user. Remove a user's ban.

Permissions: Channel:BanMembers · Rate limit: servers, 5 / 10 s

PUT /servers/{server}/bans/{target}

Ban User. Ban a user by their id.

Permissions: Channel:BanMembers · Rate limit: servers, 5 / 10 s

GET /servers/{target}/audit_logs

Audit Log Query. Queries a server's audit logs.

Permissions: Channel:ViewAuditLogs · Rate limit: servers, 5 / 10 s

GET /servers/{target}/bans

Fetch Bans. Fetch all bans on a server.

Permissions: Channel:BanMembers · Rate limit: servers, 5 / 10 s

The moderation tutorial builds /timeout and /purge.