API reference

Every route lives under /api on the site origin, and every response is JSON.

Public reads answer with an ok boolean first. Anything authenticated answers with ok: false and an error string instead of a payload, so a client can tell "the bot said no" from "the bot is unreachable".

{ "ok": true, "generatedAt": "2026-10-18T20:00:00.000Z" }

Public routes

No token, no cookies. These are cached for 30-300 seconds.

One command

GET /api/catalog/role returns the same card the bot prints in Discord:

{
  "ok": true,
  "command": {
    "name": "role",
    "aliases": ["r"],
    "category": "moderation",
    "description": "Add or remove a role from a member.",
    "usage": ",role <member> [role]",
    "cooldown": 5,
    "parameters": [
      { "name": "member", "required": true },
      { "name": "role", "required": false }
    ],
    "pages": [
      { "cmd": "all", "description": "add a role to every member", "parameters": ["(role)"] }
    ],
    "examples": [",role @User @Role", ",role all @Role"],
    "tierLabel": null,
    "premium": false,
    "docs": "/docs/commands/moderation",
    "page": "/commands/moderation/role"
  }
}

parameters is the legend: (name) and <name> are required, [name] is optional. pages is one entry per subcommand page - the same list ,role with no argument draws.

Authentication

The dashboard signs in with Discord OAuth2. The site never sees the token: it is handed back in the URL fragment after the callback and kept in the browser.

Authenticated requests send Authorization: Bearer <token> and are never cached.

Per-server routes

Every route below takes a guild id and checks that the signed-in user can manage that guild. A server the user is not in answers 403, not an empty list.

Mass DM is owner-tier: only the server owner, an extra owner, the configured owner role or a bot owner can read or start one. Every other per-server route needs only membership to read, and Manage Server to change something.

Owner routes

Bot owners only. A non-owner gets 403.

PATCH /api/guilds/:id/config answers with what it applied and what it refused, so a stale dashboard tab fails one field instead of the whole form:

{
  "ok": true,
  "applied": { "prefix": "!" },
  "failed": []
}

When the bot is unreachable

The API proxies to the bot host. If that host is down, public reads fall back to the last snapshot the bot pushed and say so in source - push, capture or build. Private routes never fall back: they answer 503 rather than inventing a server state.