Voting API

Endpoints under /api/v1/votes/queue and /api/v1/votes/claim need your listing's API key. Find it in the dashboard under Manage → Voting API key.

Authorization: Bearer mcl_your_key_here

You can also pass it as ?key= or an X-API-Key header. Keys are stored hashed, so rotate one the moment it leaks.

Public, no key needed. The endpoint most reward plugins use — has this player voted inside the last 24 hours?

curl "https://www.servershulker.com/api/v1/votes/check?server=your-slug&username=Notch"

{
  "server": "your-slug",
  "username": "Notch",
  "voted": true,
  "lastVoteAt": "2026-08-10T14:03:11.000Z",
  "cooldownHours": 24
}

Every vote you have not yet acknowledged, oldest first. Poll this on a timer — once a minute is plenty.

curl -H "Authorization: Bearer mcl_…" \
  "https://www.servershulker.com/api/v1/votes/queue?limit=100"

{
  "server": { "id": "…", "name": "Example", "slug": "example" },
  "count": 2,
  "votes": [
    { "id": "…", "username": "Notch",  "timestamp": "2026-08-10T14:03:11.000Z" },
    { "id": "…", "username": "Jeb_",   "timestamp": "2026-08-10T14:07:52.000Z" }
  ]
}

Acknowledge votes once you have given the reward. Claimed votes drop out of the queue. Omit voteIds to claim everything pending.

curl -X POST -H "Authorization: Bearer mcl_…" \
  -H "Content-Type: application/json" \
  -d '{"voteIds":["uuid-1","uuid-2"]}' \
  "https://www.servershulker.com/api/v1/votes/claim"

{ "claimed": 2 }

Claim only after the reward is safely delivered. If your plugin crashes mid-loop the vote stays in the queue and gets retried, which is the failure mode you want.

Public listing data: live status, vote totals, a 30-day history and the current featured placement. Useful for embedding your rank on your own site.

curl "https://www.servershulker.com/api/v1/servers/your-slug"

Turn it on under Manage → Votifier. We support NuVotifier (v2, a signed token) and classic Votifier (v1, RSA). v2 is what almost every modern server runs — paste the token from plugins/NuVotifier/config.yml. For v1, paste the contents of plugins/Votifier/rsa/public.key.

Delivery is attempted immediately and retried for 24 hours if your listener is unreachable, so a restart does not cost your players their rewards.

The queue endpoint allows 60 requests per minute per listing; the public check endpoint allows 120 per minute per IP. Exceed either and you get a 429 with a Retry-After header.