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. Run a Minecraft, FiveM, Roblox or Hytale server instead? The same vote checks and webhooks work for game listings, and Minecraft adds Votifier; see Game Servers.

Getting your API token

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

Every request authenticates with the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

The token identifies your listing. Endpoints never take a “which listing” 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 (or, on a Minecraft listing, a player) currently has an eligible Discordium vote for your listing, and read its own vote history and statistics.
  • stats:write: Report statistics. Report your bot's current server and shard counts. Bots only: a game server's numbers are read off the server.
  • webhooks:write: Manage webhooks. Configure the vote webhook endpoint from code (the dashboard can do this without any scope).

Where an endpoint lists more than one scope, a token holding any one of them is accepted. A token holding none of them is refused with a 401 and the code MISSING_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