Discordium Developer API

Discordium's API lets your Discord bot do three things: report its statistics (server and shard counts shown on your listing), verify votes (check whether a user currently has an eligible Discordium vote, the building block for vote rewards), and receive vote webhooks (get notified the moment someone votes). It's all plain HTTP, so there is no SDK to install.

Getting your API token

Open your bot's Discordium dashboard.
Open the Integrations tab.
Create an API token and select the scopes it needs.
Copy the token. It is shown only once.
Store it securely (see below).

Every request authenticates with the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

The token identifies your bot. Endpoints never take a “which bot” parameter as authority, so a token can only ever act on the listing it was created for. Tokens can be regenerated or revoked at any time from the same Integrations tab; both take effect immediately.

Scopes

Grant a token only what it will actually do:

votes:read: Read votes. Check whether a Discord user currently has an eligible Discordium vote for your bot, and read your bot's own vote history and statistics.
stats:write: Report statistics. Report your bot's current server and shard counts.
webhooks:write: Manage webhooks. Configure the vote webhook endpoint from code (the dashboard can do this without any scope).

Quick start

The smallest useful integration is one request: report your server count and it appears on your listing.

// The smallest useful integration: report your bot's server count.
// Node 18+, no dependencies.
await fetch("https://api.discordium.org/api/v1/bots/YOUR_BOT_ID/stats", {
    method: "POST",
    headers: {
        Authorization: `Bearer ${process.env.DISCORDIUM_API_TOKEN}`,
        "Content-Type": "application/json",
    },
    body: JSON.stringify({ serverCount: client.guilds.cache.size }),
});

From there: the Statistics guide covers periodic reporting, the Vote Checking guide covers building vote rewards, and Vote Webhooks covers being notified the moment someone votes.

Keep your token secret

Read the token from an environment variable rather than hardcoding it. DISCORDIUM_API_TOKEN is the name the examples in these docs use.

Never commit your Discordium API token to GitHub or ship it in client-side code. Discord bots run server-side, so there is no legitimate reason for the token to leave your server. If a token leaks, regenerate it in the dashboard; the old one stops working immediately.

Base URL

All endpoints in these docs are relative to:

https://api.discordium.org/api/v1