HTTP API served by the plugin’s built-in Java HttpServer (no TLS/HTTP2). It starts when api.enabled is true in config.yml and listens on api.port (default 8765).
- Base URL:
http://<host>:<port> - Auth: every endpoint requires header
X-API-Key: <api.api_key>; missing/invalid →401 Unauthorized(plain text). - Methods: only
GETis implemented. - Content types: JSON responses use
application/json;/moments/streamusestext/event-stream; error strings are plain text. - OpenAPI:
GET /openapi.jsonreturns the machine-readable OpenAPI 3.1 document (no auth required). - Time fields: epoch milliseconds unless noted. Coordinates are block coordinates unless noted. Query numbers must be valid integers; otherwise the server throws and you’ll get a 500.
- HTTPS: terminate TLS in a reverse proxy if you expose the API publicly.
Returned by /stats/*.
| Field | Type | Meaning |
|---|---|---|
uuid |
string (UUID) | Player UUID |
name |
string | Last known player name |
firstJoin |
long | First join timestamp (ms since epoch) |
lastJoin |
long | Last join/quit timestamp (ms since epoch) |
playtimeMillis |
long | Playtime in milliseconds |
deaths |
long | Total deaths |
lastDeathCause |
string|null | Last recorded death cause |
playerKills |
long | Player kills |
mobKills |
long | Mob kills |
blocksPlaced |
long | Blocks placed |
blocksBroken |
long | Blocks broken |
distanceOverworld |
double | Travel distance in the Overworld (blocks) |
distanceNether |
double | Travel distance in the Nether (blocks) |
distanceEnd |
double | Travel distance in the End (blocks) |
biomesVisited |
string[] | Visited biome names |
damageDealt |
double | Total damage dealt |
damageTaken |
double | Total damage taken |
itemsCrafted |
long | Crafted item count |
itemsConsumed |
long | Consumed item count |
Returned by /moments/*.
| Field | Type | Meaning |
|---|---|---|
id |
long | Database id |
playerId |
string (UUID) | Player UUID |
type |
string | Moment definition id (from moments.definitions.<id>) |
title |
string | Rendered title with placeholders resolved |
detail |
string | Rendered detail text |
payload |
string|null | Extra JSON payload as string (e.g. counts/fall distance) |
world |
string | World name |
x,y,z |
int | Block position |
startedAt |
long | Window start timestamp (ms) |
endedAt |
long | Window end timestamp (ms) |
Returned by /heatmap/*.
| Field | Type | Meaning |
|---|---|---|
type |
string | Heatmap type (e.g. MINING, DEATH) |
world |
string | World name |
x,z |
int | Grid indices (chunk-aligned when grid=16, otherwise scaled to the requested grid size) |
gridSize |
int | Bin size in blocks (8, 16, 32, 64) |
count |
number | Weighted hits recorded in the bin (decay applied when configured) |
Returned by /heatmap/hotspots/*.
{ "<hotspotName>": <weightedCount>, ... }
Returned by /timeline/*. Each entry is a map with keys:
day (ISO YYYY-MM-DD string), playtime_ms, blocks_broken, blocks_placed, player_kills, mob_kills, deaths, distance_overworld, distance_nether, distance_end, damage_dealt, damage_taken, items_crafted, items_consumed. Values are cumulative snapshots for that day, not per-day deltas.
Returned by /social/top.
{ "a": "<uuidA>", "b": "<uuidB>", "name_a": "<nameA>", "name_b": "<nameB>", "seconds": <long>, "shared_kills": <long>, "shared_player_kills": <long>, "shared_mob_kills": <long> } — seconds is time both players were within 16 blocks of each other; shared kill counters are kills made while the other player was within the configured radius.
Returned by /death/replay.
timestamp, uuid, name, cause, health, world, x, y, z, fallDistance, nearbyPlayers (string[]), nearbyMobs (string[]), inventory (string[]; only populated if death_replay.include_inventory_items is true).
Returned by /health.
| Field | Type | Meaning |
|---|---|---|
timestamp |
long | Capture time (ms since epoch) |
tps |
double | Server TPS (first bucket returned by Paper) |
memoryUsed |
long | Used memory (bytes) |
memoryMax |
long | Max JVM memory (bytes) |
chunks |
int | Loaded chunks (all worlds) |
entities |
int | Loaded entities (all worlds) |
hoppers |
int | Loaded hoppers (all worlds) |
redstone |
int | Count of redstone-ish block entities (droppers/dispensers/observers/pistons/etc., excluding hoppers) |
costIndex |
double | Weighted cost score (0-100) based on counts and config weights |
worlds |
object | Per-world breakdown { "<world>": { chunks, entities, hoppers, redstone } } |
hotChunks |
array | Top chunk samples: { world, x, z, entityCount, tileEntityCount, topOwner } |
Returned by /timeline/range/*. Same numeric keys as timeline entries but represent deltas over the requested range, plus from/to day strings.
Many endpoints accept a from (and optionally to) parameter for human-readable time range filtering. This provides a more intuitive alternative to epoch timestamps.
| Format | Example | Description |
|---|---|---|
| Duration | 6h, 30m, 3d, 2w |
Relative duration from now |
| Named Period | today, yesterday |
Specific day |
| Named Period | this_week, last_week |
Week boundaries (Monday-based) |
| Named Period | this_month, last_month |
Month boundaries |
| Epoch (ms) | 1700000000000 |
Raw timestamp (backwards compatibility) |
| Unit | Meaning | Example |
|---|---|---|
s |
Seconds | 30s = last 30 seconds |
m |
Minutes | 15m = last 15 minutes |
h |
Hours | 6h = last 6 hours |
d |
Days | 3d = last 3 days |
w |
Weeks | 2w = last 2 weeks |
# Get heatmap data for the last 6 hours
curl -H "X-API-Key: $API_KEY" "http://localhost:8765/heatmap/MINING?from=6h"
# Get moments from today only
curl -H "X-API-Key: $API_KEY" "http://localhost:8765/moments/recent?from=today"
# Get this week's leaderboard
curl -H "X-API-Key: $API_KEY" "http://localhost:8765/timeline/leaderboard?from=this_week"
# Get mining heatmap for a specific time window
curl -H "X-API-Key: $API_KEY" "http://localhost:8765/heatmap/MINING?from=3d&to=yesterday"The original since/until (epoch milliseconds) and days (integer) parameters still work. If both the new (from/to) and legacy parameters are provided, the new parameters take precedence.
- Purpose: machine-readable OpenAPI 3.1 document for the HTTP API.
- Auth: none (public for tooling).
- Returns the latest stats for the given player UUID.
- Errors:
400if UUID missing/invalid,404if no record.
- Returns a list of all player stats (live sessions override stored rows, sorted by name).
- Returns a JSON array of currently online player names (sorted case-insensitively).
- Purpose: recent moments snapshot.
- Query:
limit(int, default 50): Maximum moments to return.from(string): Human-readable time range (e.g.,6h,3d,today,this_week). See Time Range Filters.since(ms epoch): Legacy parameter; usefromfor human-readable syntax. If both are provided,fromtakes precedence.
- Response: list of
MomentEntry.
- Purpose: filterable moments.
- Query:
player(UUID string; ignored if invalid).type(moment id; the handler uppercases it before filtering).from(string): Human-readable time range. See Time Range Filters.since(ms epoch): Legacy parameter;fromtakes precedence if provided.limit(int, default 100).
- Response: list of
MomentEntryordered bystartedAtdesc. - Note: because the filter uppercases
typeand the DB stores the raw definition id, only all-uppercase ids will match.
- Purpose: server-sent event snapshot of moments.
- Query:
limit(int, default 50).from(string): Human-readable time range. See Time Range Filters.since(ms epoch): Legacy parameter;fromtakes precedence if provided.
- Response:
text/event-streamcontaining onedata: <MomentEntry-json>\n\nblock per moment. It sends the snapshot once; it is not a long-lived live stream.
- Purpose: aggregated heatmap data (by chunk).
- Path:
type(uppercased internally). Built-in emitters useMINING,DEATH,POSITION. - Query:
from(string): Human-readable time range start (e.g.,6h,3d,today). See Time Range Filters.to(string): Human-readable time range end.since(long, default: 7 days ago): Legacy start timestamp (ms).fromtakes precedence if provided.until(long, default: now): Legacy end timestamp (ms).totakes precedence if provided.decay(double, default: from settings): Half-life in hours for time-decay weighting. Set to 0 to disable decay.world(string, default: "world"): World name to filter by.grid(int, default: 16): Grid size for aggregation (8, 16, 32, 64).
- Response: list of
HeatmapBinrecords (chunkX, chunkZ, count/weight) ordered by weight descending. - Errors:
400 Invalid heatmap typeif an illegal value triggers anIllegalArgumentException.
- Purpose: aggregated counts for configured hotspots.
- Path:
type(uppercased internally). - Response: JSON object
{ "<hotspotName>": <count>, ... }.
- Purpose: daily snapshots for a player.
- Query:
limit(int, default 30). - Response: list of timeline day maps ordered by
daydesc. If the timeline feature is disabled, an empty list is returned. - Note: values are cumulative totals captured at autosave times, not per-day diffs.
- Purpose: aggregated deltas over a rolling range (weekly/monthly).
- Query:
from(string): Human-readable time range (e.g.,3d,this_week). See Time Range Filters. Converted to equivalent days.days(int, default 7): Legacy parameter;fromtakes precedence if provided.
- Response: map of deltas between the latest snapshot and the baseline before the window plus
from/today strings.
- Purpose: leaderboard across players for a range.
- Query:
from(string): Human-readable time range (e.g.,7d,this_week). See Time Range Filters. Converted to equivalent days.days(int, default 7): Legacy parameter;fromtakes precedence if provided.limit(int, default 20).
- Response: list of rows ordered by
playtime_msdelta (includesuuid+nameand deltas for the tracked fields).
- Purpose: pairs of players who spent the most time near each other.
- Query:
limit(int, default 50). - Response: list of social pair rows ordered by
secondsdesc. If social tracking is disabled, the list will stay empty.
- Purpose: recent captured death snapshots.
- Query:
limit(int, default 20). - Response: list of
DeathReplayEntryordered by timestamp desc. - Errors: returns
500 Erroron storage failures (logged server-side).
- Purpose: latest server health snapshot.
- Response:
HealthSnapshotwith global + per-world counts and cost index. If no sample exists yet, returns404 No samples yet.
curl -H "X-API-Key: $API_KEY" http://localhost:8765/stats/all
curl -H "X-API-Key: $API_KEY" "http://localhost:8765/moments/recent?limit=20"
curl -H "X-API-Key: $API_KEY" "http://localhost:8765/heatmap/MINING"The web dashboard is a separate HTTP server that provides a browser-based UI for viewing SMPStats data. It serves static HTML/CSS/JS files and exposes a mix of public and admin-only API endpoints.
Dashboard settings are in config.yml under the dashboard section:
dashboard:
enabled: true
bind_address: "0.0.0.0"
port: 8080
public:
enabled: true
show_online_players: true
show_leaderboards: true
show_recent_moments: true
show_server_stats: true
admin:
enabled: true
password: "ChangeThisAdminPassword"
session_timeout_minutes: 60| Key | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | true |
Enable/disable the dashboard server |
bind_address |
string | "0.0.0.0" |
Network interface to bind to |
port |
int | 8080 |
Port number for the dashboard |
public.enabled |
boolean | true |
Enable public (unauthenticated) access |
public.show_online_players |
boolean | true |
Show online players on public dashboard |
public.show_leaderboards |
boolean | true |
Show leaderboards on public dashboard |
public.show_recent_moments |
boolean | true |
Show recent moments on public dashboard |
public.show_server_stats |
boolean | true |
Show aggregated server stats |
admin.enabled |
boolean | true |
Enable admin endpoints |
admin.password |
string | "ChangeThisAdminPassword" |
Password for admin login |
admin.session_timeout_minutes |
int | 60 |
Admin session timeout in minutes |
The dashboard server provides both public and admin-protected endpoints. Admin endpoints require session-based authentication (login via /api/admin/login with password).
| Path | Description |
|---|---|
/ |
Dashboard HTML page (redirects to /index.html) |
/index.html |
Main dashboard interface |
/css/style.css |
Dashboard stylesheet |
/js/app.js |
Dashboard JavaScript application |
These endpoints do not require authentication (when public.enabled: true).
Returns the public dashboard configuration (what features are enabled).
Response:
{
"public": {
"enabled": true,
"showOnlinePlayers": true,
"showLeaderboards": true,
"showRecentMoments": true,
"showServerStats": true
},
"adminEnabled": true
}Returns currently online players.
Response:
{
"count": 5,
"players": ["Player1", "Player2", "Player3", "Player4", "Player5"]
}Returns leaderboards for various statistics.
Query Parameters:
limit(int, default 10): Maximum players per leaderboard
Response:
{
"playtime": [
{"uuid": "...", "name": "Player1", "value": 3600000}
],
"blocks_broken": [...],
"blocks_placed": [...],
"mob_kills": [...],
"player_kills": [...],
"deaths": [...],
"distance": [...]
}Returns recent moments.
Query Parameters:
limit(int, default 20): Maximum moments to return
Response:
{
"moments": [
{
"id": 1,
"playerId": "uuid",
"type": "KILL_STREAK",
"title": "Player1 achieved a 5-kill streak!",
"detail": "5 kills in 30 seconds",
"world": "world",
"x": 100,
"y": 64,
"z": -200,
"startedAt": 1234567890000,
"endedAt": 1234567920000
}
]
}Returns aggregated server statistics.
Response:
{
"totalPlayers": 150,
"totalPlaytime": 54000000000,
"totalBlocksBroken": 1234567,
"totalBlocksPlaced": 987654,
"totalMobKills": 45678,
"totalDeaths": 1234
}These endpoints require session-based authentication:
-
Login: Send a
POSTrequest to/api/admin/loginwith the password in the JSON body:{ "password": "<dashboard.admin.password>" }On success, the server responds with a session cookie (
Set-Cookie: smpstats_session=...; HttpOnly; SameSite=Strict; Secure). -
Authenticated requests: Include the session cookie in the
Cookieheader for all subsequent admin API requests.- Requests without a valid session cookie will receive
401 Unauthorized.
- Requests without a valid session cookie will receive
-
Logout: Send a request to
/api/admin/logoutto invalidate your session.
Returns all player statistics (same data as /stats/all on the main API).
Response: Array of StatsRecord objects.
Returns heatmap data for the specified type.
Path Parameters:
type: Heatmap type (MINING,DEATH,POSITION)
Query Parameters:
world(string, default "world"): World name to filtersince(long, default 7 days ago): Start timestamp (ms)until(long, default now): End timestamp (ms)limit(int, default 100): Maximum bins to return
Response:
{
"type": "MINING",
"world": "world",
"bins": [
{"chunkX": 10, "chunkZ": -5, "count": 1234}
]
}Returns timeline data for a specific player.
Path Parameters:
uuid: Player UUID
Query Parameters:
limit(int, default 30): Maximum days to return
Response:
{
"uuid": "...",
"name": "Player1",
"timeline": [
{
"day": "2024-01-15",
"playtime_ms": 3600000,
"blocks_broken": 500,
...
}
]
}Returns social interaction data (players who played together).
Query Parameters:
limit(int, default 50): Maximum pairs to return
Response:
{
"pairs": [
{
"a": "uuid1",
"b": "uuid2",
"name_a": "Player1",
"name_b": "Player2",
"seconds": 7200,
"shared_kills": 15,
"shared_player_kills": 2,
"shared_mob_kills": 13
}
]
}- Public access:
http://<host>:<dashboard.port>/— No authentication required (ifpublic.enabled: true) - Admin features: Enter the admin key in the dashboard UI to unlock admin-only views
- Security: Use a reverse proxy with TLS for production deployments