Developers

Developer documentation

Integrate Top-Server with your game server: reward voters via the API, receive real-time vote webhooks, embed badges, and use the Discord bot.

API PULL PUSH Widgets Discord bot

Vote API

Base URL: https://top-server.net

Each server has a unique API key. Find it in your dashboard → your server → Edit → API panel. The key authenticates the PULL endpoints; the per-server push secret signs PUSH webhooks. Keep both secret.

Two integration modes (combinable): PULL (your server polls us) and PUSH (we call your webhook).

PULL

GET/api/v1/vote/check

Checks whether a player has a pending (unclaimed) vote. Player match is case-insensitive.

curl

curl "https://top-server.net/api/v1/vote/check?key=VOTRE_CLE_API&player=Pseudo123"

200 OK — response

{
  "ok": true,
  "server": "Mon Serveur",
  "player": "Pseudo123",
  "hasPendingVote": true,
  "pending": 1,
  "votes": [{ "id": "ckv...", "votedAt": "2026-06-22T03:00:00.000Z" }]
}

POST/api/v1/vote/claim

Claims (consumes) a player's pending votes — call it after delivering the in-game reward. Idempotent: an already-claimed vote is never counted twice. Accepts JSON, form-urlencoded, or query string.

curl

curl -X POST "https://top-server.net/api/v1/vote/claim" \
  -H "Content-Type: application/json" \
  -d '{ "key": "VOTRE_CLE_API", "player": "Pseudo123" }'

200 OK — response

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

Errors: 400 (missing key/player), 401 (invalid API key).

PUSH (webhook)

Enable PUSH and set your webhook URL in the API panel. On every new vote, Top-Server sends a signed POST to your URL (8s timeout).

POST to your webhook — headers + body

x-topserver-event: vote
x-topserver-signature: sha256=<hmac_hex>
content-type: application/json

{
  "event": "vote",
  "serverId": "ckv...",
  "voteId": "ckv...",
  "player": "Pseudo123",
  "votedAt": "2026-06-22T03:00:00.000Z"
}

Verify the signature: compute HMAC-SHA256 of the raw body with your push secret and compare to the header.

Node.js

import crypto from "node:crypto";

function verify(rawBody, header, pushSecret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", pushSecret).update(rawBody).digest("hex");
  // comparaison à temps constant
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Tip: PUSH notifies you in real time; you can still use PULL/claim as the source of truth to mark votes as delivered.

Embeddable widgets

SVG badges you can embed anywhere (your site, Discord). No auth needed — use your server id (found in the embed panel of your dashboard).

GET/api/widget/{serverId}?type=full

type = full · votes · players · rank

HTML

<a href="https://top-server.net/server/votre-serveur">
  <img src="https://top-server.net/api/widget/SERVER_ID?type=full" alt="Top-Server" />
</a>

Discord bot

Invite the Top-Server bot to your community to surface rankings directly in Discord.

/vote

Replies with the vote link (and a button) for the server linked to this Discord.

Configurable features (per server)

Vote reminders: ping a channel (and an optional role) when the vote cooldown is over.
Live status board: a self-updating message with online status, players and 7-day uptime.
Offline alerts when the server goes down (and recovers).
Progress announcements: category rank-ups and monthly vote milestones.
New review alerts in a channel of your choice.
Wipe / event announcements from your calendar (within 24h).
Top-voter role sync (grant a Discord role to your top monthly voter).
Giveaway winner announcement in a channel of your choice.
Daily leaderboard post to a channel.
Live top-10 voters board: a self-updating message in a channel (refreshes ~every 10 min).

Toggle each feature (and the per-server master switch) in your dashboard → Edit a server → Discord bot panel. Each feature needs the relevant guild/role/channel ID.

Invite the bot:

https://discord.com/api/oauth2/authorize?client_id=1518451791166177320&permissions=268437504&scope=bot%20applications.commands

Note: newly registered global commands can take up to ~1h to appear in Discord. Top-voter role sync (granting a Discord role to your top monthly voter) is on the roadmap and requires linking Discord accounts.