API overview

The CraftRank API is a free, read-only JSON API for server owners, plugin authors and website builders. Public data needs no key. The full reference with live examples is on the API for developers page.

Base URL

https://craftrank.org/api/v1

All endpoints use GET. Public endpoints can be called from JavaScript on any website.

The server ID is in the server page address (/server/12-name) and in your dashboard.

API keys

Only the vote list needs a key. Each server has its own. Open your server's Plugin & API page in the dashboard and press Create API key. Create a new key replaces it, and the old one stops working at once. The CraftRank plugin uses the same key.

• Send it in an X-API-Key header, or as Authorization: Bearer YOUR_KEY.
• Do not put it in the address: addresses end up in logs. A ?key= parameter still works for old integrations but is deprecated.
• Call key endpoints only from your server or plugin, never from JavaScript in a web page.

Caching and rate limits

Public responses are cached for 30 seconds and /stats is updated every minute, so polling faster brings nothing new. Please do not poll more than once a minute per server. Vote checks and the vote list are never cached. Too many requests from one address are slowed down.

Response format

Responses are UTF-8 JSON. Dates are ISO 8601 with a time zone (2026-10-12T19:59:54+00:00); the vote list also gives Unix timestamps in seconds.

Errors

Errors use normal HTTP status codes and a JSON body:

{ "error": "not_found", "message": "No live server with this ID." }