API reference

Check a key: who owns it and which scopes it carries.

Scope any

Returns

{ "owner_user_id", "key_id", "scopes": [...] }

Every server the key's owner manages on the dashboard.

Scope guilds:read

Returns

{ "guilds": [{ "id", "name", "owner" }] }

One server's summary: name, icon, owner, member and online counts from the bot's latest snapshot, lifetime totals from the members the bot tracks, and the last 7 and 30 days of activity.

Scope guilds:read

Returns

{ "name", "owner_id", "icon_url", "member_count", "human_member_count", "online_count", "snapshot_refreshed_at", "totals": { "tracked_members", "messages", "voice_seconds", "xp", "wallet_coins" }, "last_7_days": { "messages", "voice_seconds", "joins", "leaves" }, "last_30_days": { ... } }

One row per day of messages, voice seconds, joins and leaves, oldest first.

Scope stats:read Query: days (1 to 365, default 30)

Returns

{ "days", "since", "entries": [{ "day": "2026-09-21", "messages", "voice_seconds", "joins", "leaves" }] }

The server's roles from the bot's snapshot.

Scope guilds:read

Returns

{ "roles": [{ "id", "name", "color" }], "refreshed_at" }

The server's channels in display order, with the category, who is in voice right now and messages in the last hour where the bot sampled them.

Scope guilds:read

Returns

{ "channels": [{ "id", "name", "type", "category_id", "position", "voice_members_now", "messages_1h" }], "refreshed_at" }

The server's custom emojis with image URLs.

Scope guilds:read

Returns

{ "emojis": [{ "id", "name", "animated", "url" }], "refreshed_at" }

Search or page through the members the bot has a record for, highest XP first. q is a user id for an exact match or part of a name.

Scope members:read Query: q, limit (1 to 200, default 50), offset

Returns

{ "members": [{ "user_id", "name", "is_bot", "xp", "level", "wallet", "messages_sent", "voice_seconds", "last_message_at" }] }

One member's full profile in this server: XP, level, rank, wallet and Bank, messages, voice, warnings, invites, bumps, daily streak, when the bot first saw them and how many times they joined and left.

Scope members:read

Returns

{ "user_id", "name", "is_bot", "xp", "level", "rank_by_xp", "wallet", "bank", "messages_sent", "voice_seconds", "warnings_count", "invites_count", "bumps_count", "daily_streak", "is_jailed", "last_message_at", "first_seen_at", "join_count", "leave_count", "currency": { "name", "emoji" } }

One member's messages and voice seconds per day.

Scope members:read Query: days (1 to 365, default 30)

Returns

{ "user_id", "days", "since", "entries": [{ "day", "messages", "voice_seconds" }] }

One member's server wallet, Bank, XP, level and message count.

Scope economy:read

Returns

{ "wallet", "bank", "xp", "level", "messages_sent", "currency": { "name", "emoji" } }

Credit (positive) or debit (negative) a member's server wallet. Goes through the bot's ledger, balance cap and economy switch, and shows in their history as dev_api:<reason>.

Scope economy:write (metered)

Body

{ "user_id": "123", "amount": 500, "reason": "quest reward" }

Returns

{ "ok": true, "moved": 500, "balance": { "wallet", "bank", ... } } or { "ok": false, "reason": "insufficient_funds" | "economy_disabled" | "limit_exceeded", "detail" }

The server's leaderboard by wallet coins, XP or messages. Up to 100 rows.

Scope economy:read Query: by (coins, xp or messages), limit (1 to 100, default 25)

Returns

{ "by", "entries": [{ "rank", "user_id", "value", "level"? }] }

One member's coin history in this server, newest first: every mint, burn, purchase, payment and your own dev_api adjustments.

Scope economy:read Query: limit (1 to 200, default 50)

Returns

{ "entries": [{ "id", "layer", "amount", "balance_after", "reason", "reference_type", "reference_id", "metadata", "created_at" }] }

Grant server XP to a member. It joins the same buffer a message's XP goes through, so the level, the level roles and the level up announcement all follow on the next flush (within a minute). Positive amounts only.

Scope levels:write (metered)

Body

{ "user_id": "123", "amount": 250, "reason": "boss kill" }

Returns

{ "ok": true, "granted": 250, "applies", "standing": { "xp", "level" } } or { "ok": false, "reason": "leveling_disabled", "detail" }

Every item in the server's shop.

Scope shop:read

Returns

{ "items": [{ "key", "label", "price_server", "stock", "extra", "category", ... }] }

Add or replace one item by key. reward "ticket" makes a hand-delivered item: buying it opens a ticket and pings the owner.

Scope shop:write

Body

{ "key": "nitro", "label": "Discord Nitro", "price_server": 5000, "reward": "ticket", "consumable": true }

Returns

{ "ok": true, "key": "nitro" }

Remove one item.

Scope shop:write

Returns

{ "ok": true }

Shop purchases from the coin ledger, newest first: who paid, how much, and their balance after. The item itself is on the buyer's inventory.

Scope economy:read Query: limit (1 to 200, default 50), offset

Returns

{ "purchases": [{ "id", "user_id", "item_key", "paid", "balance_after", "metadata", "created_at" }] }

What one member holds from the shop.

Scope economy:read

Returns

{ "items": [{ "key", "label", "category", "quantity", "updated_at" }] }

The server's custom commands.

Scope commands:read

Returns

{ "commands": [{ "name", "response", "embed" }] }

Replace the whole list. !name and "dispresso name" both answer with the response; {user}, {server}, {channel} fill in.

Scope commands:write

Body

{ "commands": [{ "name": "hype", "response": "LETS GO {user}" }] }

Returns

{ "ok": true, "count": 1 }

The case log, newest first: warns, timeouts, kicks, bans, jails and purges, with who did it and why. Filter to one member, one action, or only cases still active.

Scope moderation:read Query: user_id, action (warn, kick, ban, unban, timeout, untimeout, jail, unjail, purge), active=true, limit (1 to 200, default 50), offset

Returns

{ "cases": [{ "id", "user_id", "moderator_id", "action", "reason", "duration_seconds", "expires_at", "active", "created_at" }] }

Tickets, open ones first, with who opened and claimed them and the transcript link once closed.

Scope tickets:read Query: status (open or closed), limit (1 to 200, default 50), offset

Returns

{ "tickets": [{ "id", "number", "channel_id", "opener_id", "type_key", "claimed_by", "closed", "closed_by", "closed_at", "transcript_url", "created_at" }] }

Classic and wheel giveaways, running ones first, with the entry ids and the drawn winners.

Scope giveaways:read Query: status (active or ended), limit (1 to 100, default 25)

Returns

{ "giveaways": [{ "kind", "id", "channel_id", "message_id", "host_id", "prize", "winners", "ends_at", "ended", "required_role_id", "entry_count", "entry_ids", "winner_ids", "created_at" }] }

Who brought the most people: how many they invited, how many are still here, and how many earned the invite reward.

Scope invites:read Query: limit (1 to 100, default 25)

Returns

{ "entries": [{ "rank", "user_id", "name", "brought", "still_here", "rewarded" }] }

Everyone one member invited, with the code they used and whether they are still in the server.

Scope invites:read Query: limit (1 to 200, default 50)

Returns

{ "brought", "still_here", "invited": [{ "user_id", "invite_code", "source", "first_joined_at", "left_at", "join_count", "reward_state" }] }

Looking for group posts made from this server, open ones by default.

Scope lfg:read Query: status=all to include closed and expired, limit (1 to 100, default 25)

Returns

{ "requests": [{ "id", "author_id", "game_key", "platform", "wanted", "note", "interested", "open", "created_at", "expires_at", "closed_at" }] }

Every form in the server with its questions, the channel its button sits in, the roles allowed to press it and how many submissions it has.

Scope forms:read

Returns

{ "forms": [{ "id", "key", "title", "description", "channel_id", "button_label", "allowed_role_ids", "questions": [{ "key", "label", "style", "required", "placeholder" }], "log_channel_id", "enabled", "submissions", "created_at" }] }

The submissions of one form by its key, newest first, with the member who sent each and their answers in question order.

Scope forms:read Query: user_id, since (ISO date), limit (1 to 200, default 50), offset

Returns

{ "form_key", "submissions": [{ "id", "user_id", "username", "display_name", "answers": [{ "key", "label", "value" }], "submitted_at" }] }

Every saved embed, newest first, with the full builder payload.

Scope embeds:read

Returns

{ "embeds": [{ "id", "name", "payload", "created_by", "updated_by", "created_at", "updated_at" }] }

One saved embed.

Scope embeds:read

Returns

{ "embed": { "id", "name", "payload", ... } }

The webhooks the server saved in the builder, by id and label. The URL never leaves the server.

Scope embeds:read

Returns

{ "webhooks": [{ "id", "label", "created_at" }] }

Post a saved embed (embed_id) or a payload in the builder's own shape to a channel through the bot, or to a saved webhook. Same sender as the dashboard's Send button, so the footer and webhook branding rules of the server's tier apply.

Scope embeds:write (metered)

Body

{ "embed_id": "42", "channel_id": "123" } or { "payload": { "content": "hi", "embed": { "title": "..." } }, "webhook_id": "7" }

Returns

{ "ok": true, "message_id", "message_url", "via": "bot" | "webhook" }

Register a game server listing from your own tooling.

Scope game_servers:report (metered)

Body

{ "game_name": "Squad", "name": "EU #1", "address": "1.2.3.4", "port": 27015 }

Returns

{ "ok": true, "server_id", "server" }

Report live players, map and status for a listing you registered.

Scope game_servers:report (metered)

Body

{ "player_count": 40, "max_players": 100, "map": "Yehorivka" }

Returns

{ "ok": true, "usage" }

Read a listing you registered.

Scope game_servers:read

Returns

{ "server" }