Server vote rewards API

What it does

Players can vote for a server on its WardogsHub page once per day. The vote check API lets you ask whether a given Discord account has done so, so you can reward them with a role, a perk or a place in a draw.

1. A member votes for your server on WardogsHub.
2. They run /claimvote in your Discord server.
3. Your bot asks WardogsHub whether their Discord account voted today.
4. If it did, your bot gives them the reward role.

Get your API key

1. Sign in at wardogshub.gg with the Discord account that submitted the listing.
2. Open Your servers.
3. Click Edit on the approved listing.
4. In the "Vote rewards API" section, click Generate key.

The key is shown once, so copy it somewhere safe. Regenerating replaces it, and the old key stops working immediately. Keys start with wdh_ followed by 43 URL-safe characters. There is one key per listing, and it identifies your server, so requests never name one.

Listings we added ourselves have no owner account yet and cannot generate a key. If that is yours,contact us to claim it.

Check a vote

GET https://wardogshub.gg/api/v1/votes/check?discord_id=<id>

discord_id is a Discord user ID (17 to 20 digits). Send your key in the Authorization header as a bearer token.

curl "https://wardogshub.gg/api/v1/votes/check?discord_id=123456789012345678" \
  -H "Authorization: Bearer wdh_YOUR_KEY"

Response

{
  "server": { "id": "3f2a…", "name": "Example Community" },
  "discord_id": "123456789012345678",
  "voted": true,
  "last_vote_at": "2026-10-14T09:12:00.000Z",
  "resets_at": "2026-10-15T00:00:00.000Z"
}

If a Discord ID has never signed in to WardogsHub, the answer is simply voted: false and last_vote_at: null. We do not reveal whether an account exists.

Errors and rate limit

Errors are JSON in the form { "error": "message" }. Each key may make 120 requests per minute, and one IP address 300; past that you get a 429 with a Retry-After header in seconds.

Example code

Node.js (18 or newer)

const res = await fetch(
  `https://wardogshub.gg/api/v1/votes/check?discord_id=${discordId}`,
  { headers: { Authorization: `Bearer ${process.env.WARDOGSHUB_API_KEY}` } },
);

if (res.status === 429) {
  console.log('Rate limited, retry in', res.headers.get('Retry-After'), 'seconds');
} else if (!res.ok) {
  throw new Error((await res.json()).error);
} else {
  const { voted } = await res.json();
  if (voted) { /* give the reward */ }
}

Python

import os
import requests

res = requests.get(
    "https://wardogshub.gg/api/v1/votes/check",
    params={"discord_id": discord_id},
    headers={"Authorization": f"Bearer {os.environ['WARDOGSHUB_API_KEY']}"},
    timeout=10,
)

if res.status_code == 429:
    print("Rate limited, retry in", res.headers.get("Retry-After"), "seconds")
else:
    res.raise_for_status()
    if res.json()["voted"]:
        pass  # give the reward

Make these calls from a server or bot you control, never from a client app or a web page.

Ready-made Discord bot

A small discord.js bot that does the whole flow. Members run /claimvote; if their vote is found the bot adds your reward role, otherwise it replies with your vote link. It can also remove the role after a set number of hours (24 by default).

The code is open source on GitHub, with setup steps, a Dockerfile and updates. Report problems there as issues. If you would rather not use git, GitHub's Code button has a Download ZIP option.

Quick start

1. Create a Discord application and bot, and invite it with the bot and applications.commands scopes and the Manage Roles permission.
2. Drag the bot's role above the reward role in Server Settings, or Discord will refuse to hand it out.
3. Get your API key as above.
4. Run the commands below on any machine that stays on, filling in .env before npm start. You need Node 18 or newer, or use the Dockerfile in the repository.

git clone https://github.com/Wardogs-Hub/vote-bot.git
cd vote-bot
cp .env.example .env   # then fill in .env
npm install
npm start

Rules and fair use

• One vote per Discord account per server per UTC day. The day rolls over at 00:00 UTC.
• The vote must come from the same Discord account the member uses in your Discord server.
• Rewarding votes is fine. Do not require a vote to join or play on your server.
• Do not pay for votes and do not use alt accounts.
• Keep your key secret. Never put it in a Discord message, a client app or a public repository.

We may revoke keys or remove listings that break these rules.

Privacy

By voting, a player lets the owner of that server check whether their Discord account voted for it. Nothing else is shared: not their name, email or other votes. See the privacy policy.

FAQ

Elsewhere

• Server list

  Every community server, with its vote link.

• Your servers

  Generate or replace your API key.

• Contact

  Claim a listing we added, or ask a question.