API Reference

Seven GET endpoints, all returning application/json. Each card below mirrors the handler as it ships.

Base URL & auth

All routes are served from the plugin's embedded HTTP server at the host and port you configure (default 0.0.0.0:8080). Every response is application/json.

All routes are GET-only; any other method gets 405.
When security.enable-api-key is on with a non-blank key, every route requires Authorization: Bearer <key>.
When security.enable-cors is on, OPTIONS preflights return 204.

GET/api/healthAuth applies

Health check

Liveness probe with server, memory, feature-flag, and executor snapshots. Ideal for uptime monitors and status pages.

Request

curl http://localhost:8080/api/health \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "system": {
    "status": "ok",
    "timestamp": "2026-09-12T18:42:07.113Z",
    "uptime_seconds": 86412,
    "plugin_version": "1.0.0",
    "minecraft_version": "1.16.5",
    "server_version": "git-Paper-794",
    "bukkit_version": "1.16.5-R0.1-SNAPSHOT"
  },
  "players": { "online": 42, "max": 100 },
  "memory": {
    "used_mb": 2048, "free_mb": 1024, "max_mb": 4096,
    "heap_used_mb": 1980, "heap_committed_mb": 3072, "heap_max_mb": 4096
  },
  "features": {
    "https_enabled": false,
    "compression_enabled": true,
    "async_enabled": true,
    "rate_limit_enabled": true,
    "api_auth_enabled": true,
    "docs_enabled": true
  },
  "executor": { "active": 2 }
}

GET/apiAuth applies

API index

Minimal service descriptor. Handy as a smoke test that the HTTP server is up and which build is running.

Request

curl http://localhost:8080/api

Response

{
  "name": "Statfyr",
  "version": "1.0.0",
  "docs": "/api/docs"
}

GET/api/docsAuth applies

Self-hosted route index

Machine-readable index of the live API routes served by this instance. Consumed by generators and SDK scaffolding.

Request

curl http://localhost:8080/api/docs

Response

{
  "routes": [
    "/api/health",
    "/api/players",
    "/api/player/{uuid}",
    "/api/player/{name}",
    "/api/player/{id}/summary",
    "/api/leaderboard/{stat}",
    "/api/docs"
  ]
}

GET/api/playersAuth applies

List players

Paginated roster of tracked players, sorted by name, with live online status. Supports search by name substring and an online-only filter.

Request

curl "http://localhost:8080/api/players?limit=2&page=0&search=ste" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "total": 1,
  "limit": 2,
  "page": 0,
  "offset": 0,
  "players": [
    {
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "name": "Notch",
      "online": true
    }
  ],
  "metadata": {
    "generated_at": "2026-09-12T18:42:07.401Z",
    "execution_time_ms": 3,
    "ascending": true,
    "online_only": false,
    "search": "ste"
  }
}

GET/api/player/{id}Auth applies

Full player statistics

Complete statistic profile for a player by UUID or exact current name: computed summary metrics plus raw per-category Minecraft statistic maps. Reads live Bukkit statistics for online players and the world/stats JSON files for offline players.

Request

curl http://localhost:8080/api/player/069a79f4-44e9-4726-a5be-fca90e38aaf5 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "name": "Notch",
  "online": true,
  "readTimestamp": "2026-09-12T18:42:07.552Z",
  "summary": {
    "playTimeTicks": 21894400,
    "playTimeFormatted": "15d 4h 50m",
    "deaths": 128,
    "playerKills": 41,
    "mobKills": 3140,
    "damageDealt": 512094,
    "damageTaken": 388712,
    "jumps": 92044,
    "distanceCm": 482034118,
    "distanceKm": 4820.34,
    "chestsOpened": 7433,
    "itemsCrafted": 21843,
    "itemsBroken": 812,
    "itemsUsed": 104552,
    "itemsDropped": 4211,
    "itemsPickedUp": 88210,
    "blocksMined": 318402
  },
  "minecraft:mined": {
    "minecraft:sand": 12044,
    "minecraft:stone": 184022
  },
  "minecraft:custom": {
    "minecraft:deaths": 128,
    "minecraft:player_kills": 41
  },
  "stats": { "...": "full unmodified Bukkit statistic dump" },
  "metadata": {
    "generated_at": "2026-09-12T18:42:07.552Z",
    "execution_time_ms": 12,
    "summary_enabled": true,
    "raw_enabled": true,
    "categories_filter": null
  }
}

GET/api/player/{id}/summaryAuth applies

Player summary

Aggregated, snake_case view of a player optimized for dashboards and cards. Each section (combat, movement, activity) can be toggled off to slim the payload.

Request

curl http://localhost:8080/api/player/Notch/summary \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "name": "Notch",
  "online": true,
  "playtime_ticks": 21894400,
  "playtime_seconds": 1094720,
  "playtime_formatted": "15d 4h 50m",
  "combat": {
    "deaths": 128,
    "player_kills": 41,
    "mob_kills": 3140,
    "damage_dealt": 512094,
    "damage_taken": 388712
  },
  "movement": {
    "distance_walked_cm": 221034511,
    "distance_walked_m": 2210345.11,
    "distance_sprinted_cm": 150223044,
    "distance_sprinted_m": 1502230.44,
    "distance_flown_cm": 4102299,
    "distance_flown_m": 41022.99,
    "distance_swum_cm": 8823011,
    "distance_swum_m": 88230.11,
    "total_distance_cm": 482034118,
    "total_distance_m": 4820341.18,
    "total_distance_km": 4820.34,
    "jumps": 92044
  },
  "activity": {
    "chests_opened": 7433,
    "items_crafted": 21843,
    "items_broken": 812,
    "items_used": 104552,
    "items_picked_up": 88210,
    "items_dropped": 4211,
    "blocks_mined": 318402
  },
  "metadata": {
    "generated_at": "2026-09-12T18:42:07.601Z",
    "execution_time_ms": 8
  }
}

GET/api/leaderboard/{stat}Auth applies

Leaderboard

Ranked standings for a statistic. Accepts built-in metric names, dotted category.key aliases, full vanilla stat keys, and custom stats registered by other plugins.

Request

curl "http://localhost:8080/api/leaderboard/playtime?limit=3" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "stat": "playtime",
  "total": 1284,
  "limit": 3,
  "offset": 0,
  "page": 0,
  "entries": [
    {
      "rank": 1,
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "name": "Notch",
      "online": true,
      "value": 21894400,
      "formatted": "15d 4h 50m"
    },
    {
      "rank": 2,
      "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
      "name": "jeb_",
      "online": false,
      "value": 19020044,
      "formatted": "13d 4h 20m"
    },
    {
      "rank": 3,
      "uuid": "61699b2e-d327-4a01-9f1e-0ea8c3f06bc6",
      "name": "Dinnerbone",
      "online": false,
      "value": 15411220,
      "formatted": "10d 17h 25m"
    }
  ],
  "metadata": {
    "generated_at": "2026-09-12T18:42:07.733Z",
    "execution_time_ms": 21,
    "ascending": false,
    "online_only": false
  }
}

Leaderboard stat keys

Built-in stat names (bare words), dotted category.key aliases, full vanilla keys like minecraft:mined:minecraft:sand, and custom plugin stats are all accepted. These seven are the hard-coded entries:

Key	Measures
`playtime`	Total play time (adds human-readable formatted)
`deaths`	Death count
`player_kills`	Players killed
`mob_kills`	Mobs killed
`blocks_mined`	Blocks mined
`items_picked_up`	Items picked up
`items_crafted`	Items crafted

Error shape

Every error response (except the "Stats not found" soft error) follows this schema:

{
  "success": false,
  "status": 429,
  "error": "Rate limit exceeded",
  "timestamp": "2026-09-12T18:42:08.101Z"
}

Status codes

Code	Meaning
`200`	Success (including the "Stats not found" soft-error body).
`400`	Malformed query parameter or path argument.
`401`	Missing/invalid Bearer key while security.enable-api-key is on.
`403`	Requester IP not in security.allowed-ips while the whitelist is enabled.
`404`	Unknown route, unknown player, or unknown leaderboard stat.
`405`	Method other than GET (all routes are GET-only).
`429`	Per-IP fixed-window rate limit exceeded.
`500`	Internal handler error.

← PreviousConfiguration Reference Next →Integration Examples