Web API

Requires the WEB_API feature; the moderate and write scopes additionally require WEB_API_WRITE.

HepBoat exposes a versioned HTTP API (/api/v1) so you can pull your server's data into your own tooling, or drive moderation from outside Discord. This page covers keys, scopes, and limits; the endpoint reference documents every endpoint with parameters, response shapes, and curl examples.

API keys

Keys are created on the dashboard's API page (admin access required). The secret is shown once at creation and only its hash is stored - if you lose it, revoke the key and generate a new one. Each key belongs to the server it was created for; it never works against another server's URLs.

Using a key

Send the key as a bearer token. Keys start with hbk_:

curl -H "Authorization: Bearer hbk_..." \
  https://<dashboard-host>/api/v1/guilds/<guild-id>/infractions

The API page shows a ready-to-run example against your own server with your dashboard host and server ID filled in.

Scopes

Each key carries one or more scopes:

Scope	Allows
read	read infractions, bans, users, stats, levels, tags, economy
import	bulk-import historical infractions
export	export all infractions as JSON
moderate	issue and reverse moderation actions
write	edit infractions, tags, and XP

moderate and write are the elevated pair: keys carrying them only work while the server holds WEB_API_WRITE. Existing keys can always be listed and revoked, even after a feature downgrade.

Moderation keys can target anyone

API moderation deliberately bypasses the bot's level hierarchy. A key with the moderate scope can ban, kick, or mute any member - moderators, admins, even the server owner. Only Discord's own role position limits what the bot can physically do. This is intentional: it lets you build security tooling that can act on your own staff if one of their accounts is compromised. The flip side is that a leaked moderate or write key is as dangerous as a leaked owner account - treat those keys like the owner's password. The one target the API always refuses is the bot itself: an action against the bot's own account fails instead of running.

Rate limits

Every key is limited to 120 requests per minute. Going over returns 429 with {"error": "rate limit exceeded", "limit_per_min": 120} - back off and retry after the minute rolls over. Two endpoints carry their own additional limits: export runs once per 30 days, and import has a cumulative per-server quota. Both are covered in the reference.

Errors

Errors are JSON with an error field describing what went wrong:

Status	Meaning
400	malformed request (bad JSON, invalid parameters)
401	missing bearer token
403	invalid or revoked key, wrong server, missing scope, or missing feature
404	the resource does not exist in this server
409	The request conflicts with current state: your import quota is exhausted, or an identical Idempotency-Key is still in flight.
429	rate limit exceeded, or the export throttle
503	the database is temporarily unavailable - retry later

Good to know

• Actions issued over the API create real infractions: they are numbered, they hit the mod log, timed ones expire, and they are attributed to the API key so the audit trail shows exactly what came from automation.
• Actions are durably queued - an action accepted by the API is carried out even if a restart lands in between. The reference documents the accept-then-poll flow.
• Revoking a key on the API page cuts it off immediately.