API • MCStatistics

Authentication

MCStatistics API v2 supports server secret authentication for plugins and User JWT authentication for dashboard/user-owned server management.

Auth type	Used for	Preferred header
Server secret	Minecraft plugins, server-side submissions, `/servers/me/...`	`Authorization: Server <secret>`
User JWT	Dashboard/user-owned server management	`Authorization: Bearer <jwt>`

Server Secret

Authorization: Server your-server-secret

Legacy clients may also use X-MCStatistics-Secret: your-server-secret.

User JWT

Authorization: Bearer your-user-jwt

JWT auth is used for account/user scoped routes and accessing specific servers by id.

The `:server` Route Parameter

Most server-data endpoints use /v2/servers/:server/....

Value	Auth required	Meaning
`me`	Server secret	The server authenticated by the server secret
`serverId`	User JWT	A specific server id the JWT user can access

GET /v2/servers/me/players
Authorization: Server your-server-secret

GET /v2/servers/60ca4db77e26242a8b198053/players
Authorization: Bearer your-user-jwt

Server groups: a group cannot submit data directly. Read endpoints usually merge child/subserver data automatically and may support ?server=Survival to filter by subserver name.

Scopes

Authenticated users can access their own user/server resources. To access resources owned by another user the JWT user must have shared access or have a matching scope.

User scopes

users:read:any — Read any user resource
users:write:any — Write any user resource
users:read:<userId> — Read one user resource
users:write:<userId> — Write one user resource

Server scopes

servers:read:any — Read any server data
servers:write:any — Manage any server
servers:submit:any — Submit data to any server
servers:read:<serverId> — Read one server
servers:write:<serverId> — Manage one server
servers:submit:<serverId> — Submit data to one server

Standard Response Format

v2 responses are direct JSON and are not wrapped in success / data by default.

Success

{
  "servers": []
}

Queued operation

{
  "queued": true,
  "job_id": "server-stats__60ca4db77e26242a8b198053__1785790000000"
}

Error format

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Something went wrong."
  }
}

Status	Meaning
`400`	Invalid request
`401`	Missing or invalid authentication
`403`	Authenticated but not allowed
`404`	Resource not found
`409`	Conflict, such as duplicate server name
`202`	Accepted and queued
`500`	Internal server error

Common Query Parameters

Pagination

page — Page number, usually defaults to 1
limit — Results per page

Time filters

from — Start timestamp in milliseconds
to — End timestamp in milliseconds
range — Relative range when from is not provided
interval — Graph bucket interval

Ranges: 1h, 6h, 24h, 7d, 30d, 6m, 1y. For range, m means months. For graph interval, m means minutes.

Endpoint Overview

User Management

GET    /v2/users/:user/servers - List user servers
POST   /v2/users/:user/servers - Create new server

Server

GET    /v2/servers/:server/                - Show server details
PATCH  /v2/servers/:server/                - Update server configuration
DELETE /v2/servers/:server/                - Delete server
GET    /v2/servers/:server/subservers      - List all subservers
GET    /v2/servers/:server/results         - Shows latests server results
GET    /v2/servers/:server/performance     - Shows server performance

Players

GET /v2/servers/:server/players                             - Lists players
GET /v2/servers/:server/players/:player                     - Shows player details
GET /v2/servers/:server/players/:player/sessions            - Shows players latest sessions
GET /v2/servers/:server/players/:player/ip-history          - Shows player ip history
GET /v2/servers/:server/players/:player/activity            - Shows player activity as graph values
GET /v2/servers/:server/players/:player/data-fields         - Shows player stored data fields
GET /v2/servers/:server/players/:player/data-fields/graph   - Shows player stored data fields as graphs values

Server Submission

POST /v2/servers/:server/serverStatistics
POST /v2/servers/:server/newSession

Submit Server Statistics body

{
  "players-online": 12,
  "tps": 19.95,
  "allocated-memory": 2147483648,
  "free-memory": 1073741824,
  "worlds": [
    {
      "name": "world",
      "entities": 230,
      "chunks_loaded": 1400
    }
  ],
  "players": [
    {
      "identifier": "00000000-0000-0000-0000-000000000000",
      "username": "Steve",
      "version": 767,
      "data": {
        "money": 2500,
        "rank": "VIP",
        "level": 12
      }
    }
  ]
}

Graphs

GET /v2/servers/:server/graphs/dashboard
GET /v2/servers/:server/graphs/players
GET /v2/servers/:server/graphs/performance

Data Fields

GET   /v2/servers/:server/data-fields
GET   /v2/servers/:server/data-fields/:key
PATCH /v2/servers/:server/data-fields/:key
GET   /v2/servers/:server/data-fields/:key/leaderboard
GET   /v2/servers/:server/data-fields/:key/graph

Data fields are dynamic values stored in player or session data, such as kills, deaths, money, rank, level, wins and losses.

Webhooks

GET    /v2/servers/:server/webhooks
POST   /v2/servers/:server/webhooks
GET    /v2/servers/:server/webhooks/:webhook_id
PATCH  /v2/servers/:server/webhooks/:webhook_id
DELETE /v2/servers/:server/webhooks/:webhook_id

Supported webhook events

daily_report new_player new_player_session new_server_data new_player_record

Time and Version Rules

Timestamps

All timestamps are milliseconds unless otherwise stated. last_updated uses seconds. Graph labels are UTC formatted strings.

Minecraft versions

Many endpoints return both version_protocol and readable version. Unknown protocol versions return Unknown (999).

Example Integration Flow

Plugin/server-secret flow

POST /v2/servers/me/statistics
Authorization: Server your-server-secret

POST /v2/servers/me/sessions
Authorization: Server your-server-secret

GET /v2/servers/me/players/00000000-0000-0000-0000-000000000000
Authorization: Server your-server-secret

GET /v2/servers/me/graphs/performance?range=7d&interval=auto
Authorization: Server your-server-secret

Dashboard/JWT flow

GET /v2/users/me/servers
Authorization: Bearer your-user-jwt

GET /v2/servers/60ca4db77e26242a8b198053/graphs/dashboard?range=7d
Authorization: Bearer your-user-jwt

PATCH /v2/users/me/servers/60ca4db77e26242a8b198053
Authorization: Bearer your-user-jwt
Content-Type: application/json

{
  "name": "Survival Updated"
}

API Documentation