Public API

BlockFront has a public API that serves live stats, player profiles, brigades and match results as JSON. This section covers how to use it.

Making a request

All requests are GET, and the type parameter picks the route:

https://api.blockfrontmc.com/api/v2/?type=player_count

{ "playersOnline": 97 }

API keys

Player, brigade and match routes need an API key, sent in the X-API-Key header:

curl -H "X-API-Key: name:secret" "https://api.blockfrontmc.com/api/v2/?type=player&name=Example"

API keys are private, and we strictly give them out only to individuals we know we can trust. If you have one, keep it secret and never put it in code that runs in a browser.

Route	Key needed
player_count	No
scoreboard	No
map_stats	No
map_ratings	No
player	Yes
player_matches	Yes
clan	Yes
match	Yes

Rate limits

Request	Limit
Without a key	4 per second, per address
With a key	20 per second, per address, and 10 per second per key

Going over returns a 429, so space your requests out.

Errors

Every error has the same shape:

{
  "error": {
    "code": "key_required",
    "message": "This route needs an API key in the X-API-Key header"
  }
}

Status	Code	Meaning
400	missing_type	The type parameter is missing.
400	bad_request	A parameter is missing or malformed.
401	key_required	The route needs an API key.
403	opted_out	The player has opted out of the API.
404	not_found	Nothing matches the request.
404	unknown_route	No route has that name.
405	method_not_allowed	The route doesn’t accept that method.
429	rate_limited	Too many requests.
500	internal_error	Something went wrong on our side.
503	overloaded	The API is busy. Wait for the Retry-After header’s number of seconds.
503	module_disabled	That feature is switched off for now.

Privacy

Players can turn on Hide From Stats Sites in their privacy settings:

• player and player_matches return 403 opted_out for them.
• Brigade rosters and match scoreboards keep their entry but replace their name and id with "hidden": true.

Please respect this, and don’t store or show data on players who’ve opted out.

Caching

scoreboard responses have Cache-Control and ETag headers. Send the ETag back as If-None-Match and you’ll get a 304 if nothing has changed.