API
Plugin setup
No compiled jar is published on this site right now. The plugin is a build output, not a checked-in file, and this installation has not produced one · so there is nothing to download and we are not going to pretend otherwise.
The full source is in plugin/ in the site's repository. It needs Java 21 and Maven, has no runtime dependencies of its own, and builds in about a minute:
mvn -f plugin/pom.xml clean package
# → plugin/target/VotingSite-<version>.jarCopy that jar into your server's plugins/ folder and restart. Then set site.url to https://voxelrank.com and site.api-key to your API key in plugins/VotingSite/config.yml. Once this site has run the build once, a download button with a checksum appears here instead.
You do not need the plugin at all if you use Votifier: fill in the Votifier details on your server's edit page and votes are delivered directly, no plugin involved.
Every server gets an API key on creation · find it in your Dashboard. Keys are rate limited to 120 requests/minute.
No compiled plugin jar is published here yet · build it from source with mvn -f plugin/pom.xml clean package, or skip the plugin entirely and use Votifier.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/servers?q=&tag=&version=&page= | Public server list as JSON. |
| GET | /api/servers/status?ids=1,2,3 | Live player counts for the given servers. |
| GET | /api/v1/server?key=API_KEY | Your server, its rank and vote totals. |
| GET | /api/v1/votes/unclaimed?key=API_KEY | Votes not yet rewarded. Returns [{id,username,timestamp}]. |
| POST | /api/v1/votes/claim | Body {"key":"…","ids":[1,2]} · marks votes as rewarded. |
| GET | /api/v1/votes/check?key=API_KEY&username=X | Has this player voted in the last 24h? |
| GET | /api/v1/top?key=API_KEY&limit=10 | Monthly top voters for your server. |
| GET | /api/v1/referral/check?key=API_KEY&username=X | Does this player have a claimable welcome referral? Read-only, safe to poll. |
| POST | /api/v1/referral/claim | Body {"key":"…","username":"X"} · grants and consumes the referral. granted:true at most once per player per 30 days. |
| GET | /banner/:slug.svg | Vote banner image (468x60). Add ?small=1 for 350x20. |
Example · claim votes from a plugin
curl "https://voxelrank.com/api/v1/votes/unclaimed?key=YOUR_KEY"
# [{"id":91,"username":"Notch","timestamp":1718900000}]
curl -X POST "https://voxelrank.com/api/v1/votes/claim" \
-H "Content-Type: application/json" \
-d '{"key":"YOUR_KEY","ids":[91]}'
# {"claimed":1}Example · the welcome referral
curl -X POST "https://voxelrank.com/api/v1/referral/claim" \
-H "Content-Type: application/json" \
-d '{"key":"YOUR_KEY","username":"Notch"}'
# {"granted":true,"reason":"ok","source":"vote","seen_ago":3400,…}What granted means: that username interacted with your listing here in the last 7 days · it voted for you, or it was entered in the "tell them we sent you" box on your page · and we have just handed you that claim exclusively. It does not mean the player provably followed a link from here. Nothing can establish that: a web page and a Minecraft login share no identity, and a player who never visited can type their name in and collect. Every response carries a disclaimer field saying so. Give a welcome kit, not something worth farming. A claim is consumed by the call, so ask only when you are about to run the reward.
Votifier
If you fill in Votifier details on your server's edit page, votes are pushed to your server the instant they are cast (v2 token or v1 RSA, auto-detected) · no polling needed. The REST API stays available as a fallback for votes cast while the server was offline.