Skip to content

Api reference

Jump to bottom
Ashutosh Das edited this page May 20, 2026 · 1 revision

API Reference

All Statfyr API endpoints are served under the base URL:

http://your-server:8080/api

All responses are application/json. Errors follow a consistent format.

Response Format

Success:

{
  "success": true,
  ...
}

Error:

{
  "success": false,
  "status": 404,
  "error": "Player not found"
}

Endpoints

GET /api/health

Returns server and plugin health information. Useful for monitoring and uptime checks.

No parameters.

Example Request:

GET /api/health

Example Response:

{
  "status": "ok",
  "plugin_version": "1.0.0-BETA",
  "server_version": "git-Paper-790",
  "bukkit_version": "1.21.10-R0.1-SNAPSHOT",
  "online_players": 3,
  "minecraft_version": "1.21.10",
  "uptime_seconds": 5400
}

GET /api/players

Returns a paginated list of all known players.

Query Parameters:

Parameter Type Required Default Description
limit integer No 25 Maximum number of players to return (max: 100)
page integer No 1 Page number
order string No desc Sort order — asc or desc
online_only boolean No false Return only currently online players
search string No — Filter by player name (partial match)

Example Request:

GET /api/players?limit=10&page=1&online_only=true

Example Response:

{
  "total": 2,
  "limit": 10,
  "page": 1,
  "offset": 0,
  "players": [
    {
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Steve",
      "online": true
    },
    {
      "uuid": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "name": "Alex",
      "online": true
    }
  ]
}

GET /api/player/{player}

Returns complete statistics for a single player.

{player} can be either a UUID or a player name.

Query Parameters:

Parameter Type Required Default Description
summary boolean No true Include the summary block
raw boolean No false Include raw Minecraft stat values
categories string No all Comma-separated list of stat categories to include. Options: mined, crafted, used, broken, picked_up, dropped, killed, killed_by

Example Requests:

GET /api/player/Steve
GET /api/player/Steve?summary=true&raw=false&categories=mined,crafted
GET /api/player/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Example Response:

{
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "Steve",
  "online": true,
  "summary": {
    "playTimeTicks": 123456,
    "playTimeFormatted": "1d 2h 30m",
    "deaths": 5,
    "playerKills": 10,
    "mobKills": 250
  },
  "crafted": {
    "minecraft:diamond_pickaxe": 2
  },
  "mined": {
    "minecraft:diamond_ore": 120
  }
}

GET /api/player/{player}/summary

Returns a lightweight, structured summary of a player's statistics. More efficient than the full stats endpoint when you only need aggregated data.

{player} can be either a UUID or a player name.

Query Parameters:

Parameter Type Required Default Description
movement boolean No true Include movement stats
combat boolean No true Include combat stats
activity boolean No true Include activity stats

Example Request:

GET /api/player/Steve/summary
GET /api/player/Steve/summary?movement=true&combat=true&activity=false

Example Response:

{
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "Alex",
  "online": false,
  "playtime_ticks": 125,
  "playtime_seconds": 6,
  "playtime_formatted": "6s",
  "combat": {
    "deaths": 0,
    "player_kills": 0,
    "mob_kills": 0,
    "damage_dealt": 0,
    "damage_taken": 0
  },
  "movement": {
    "distance_walked_cm": 0,
    "distance_walked_m": 0,
    "distance_sprinted_cm": 0,
    "distance_sprinted_m": 0,
    "distance_flown_cm": 0,
    "distance_flown_m": 0,
    "distance_swum_cm": 0,
    "distance_swum_m": 0,
    "total_distance_cm": 0,
    "total_distance_m": 0,
    "total_distance_km": 0,
    "jumps": 0
  },
  "activity": {
    "chests_opened": 0,
    "items_crafted": 0,
    "items_broken": 0,
    "items_used": 0,
    "items_picked_up": 0,
    "items_dropped": 0,
    "blocks_mined": 0
  },
  "metadata": {
    "generated_at": "2026-05-20T11:17:16.252462500Z",
    "execution_time_ms": 34,
    "movement_enabled": true,
    "combat_enabled": true,
    "activity_enabled": true
  }
}

Summary Fields Reference

Combat:

Field Description
deaths Total deaths
player_kills Players killed
mob_kills Mobs killed
damage_dealt Total damage dealt
damage_taken Total damage taken

Movement:

Field Description
distance_walked_cm / _m Distance walked
distance_sprinted_cm / _m Distance sprinted
distance_flown_cm / _m Distance flown
distance_swum_cm / _m Distance swum
total_distance_cm / _m / _km Total movement distance
jumps Number of jumps

Activity:

Field Description
chests_opened Chests opened
items_crafted Items crafted
items_broken Tools/items broken
items_used Items used
items_picked_up Items picked up
items_dropped Items dropped
blocks_mined Total blocks mined

GET /api/leaderboard/{type}

Returns a ranked leaderboard for the given stat type.

Supported Types:

Type Description
playtime Sorted by total playtime (ticks)
kills Sorted by mob + player kills
deaths Sorted by total deaths
mined Sorted by total blocks mined
crafted Sorted by total items crafted

Query Parameters:

Parameter Type Required Default Description
limit integer No 25 Number of entries to return (max: 100)
page integer No 1 Page number
order string No desc Sort direction — asc or desc

Example Request:

GET /api/leaderboard/playtime?limit=10&order=desc

Example Response:

{
  "stat": "playtime",
  "total": 1,
  "limit": 25,
  "offset": 0,
  "page": 1,
  "entries": [
    {
      "rank": 1,
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Steve",
      "online": false,
      "value": 125,
      "formatted": "6s"
    }
  ],
  "metadata": {
    "generated_at": "2026-05-20T11:18:07.625703400Z",
    "execution_time_ms": 3,
    "ascending": false,
    "online_only": false
  }
}

HTTP Status Codes

Code Meaning
200 Success
400 Bad request — invalid or missing parameters
401 Unauthorized — API key missing or invalid
403 Forbidden — IP not in whitelist
404 Not found — player or resource doesn't exist
405 Method not allowed
429 Too many requests — rate limit exceeded
500 Internal server error

Compression

If compression.enabled: true in the config, include the following header to receive a gzip-compressed response:

Accept-Encoding: gzip

Interactive Docs

A browsable version of this documentation is available directly on your server at:

http://your-server:8080/api/docs

Next: Authentication & Security

Clone this wiki locally