REST API

REST API

The serverdoctor-rest-api module exposes ServerDoctor's latest data over HTTP as JSON. It is read-only — it never triggers actions or changes anything — and is built on the JDK's built-in HTTP server, so it adds no external dependencies.

Enabling

rest-api:
  enabled: true
  host: "127.0.0.1"   # localhost only; use 0.0.0.0 to expose it (then set a token!)
  port: 9173
  token: ""           # optional bearer token

Restart the server/proxy after changing the config. On start you'll see a log line like REST API listening on http://127.0.0.1:9173.

Authentication

If token is set, every endpoint except /health requires:

Authorization: Bearer <token>

Requests without it get 401. If token is empty, all endpoints are open — only do that on a trusted/localhost bind.

Binding to 0.0.0.0 exposes the API to the network. In that case always set a token and/or place it behind a reverse proxy with TLS.

Endpoints

All endpoints are GET and return application/json.

Path	Auth	Returns
/health	no	{ "status": "ok", "name": "ServerDoctor", "version": "…" }
/performance	token	latest TPS/MSPT/memory snapshot
/conflicts	token	array of detected conflicts
/security	token	array of security / maintenance risks
/recommendations	token	array of recommendations
/report	token	latest full report (404 if none yet)

Examples

curl http://127.0.0.1:9173/health

curl -H "Authorization: Bearer <token>" http://127.0.0.1:9173/performance
curl -H "Authorization: Bearer <token>" http://127.0.0.1:9173/report

Sample /performance response

{
  "tps1m": 19.98,
  "tps5m": 19.95,
  "tps15m": 20.0,
  "mspt": 3.21,
  "memory": {
    "usedBytes": 2147483648,
    "maxBytes": 4294967296,
    "usedMb": 2048,
    "maxMb": 4096,
    "usedRatio": 0.5,
    "gcCount": 42,
    "gcTimeMs": 311
  },
  "threads": 78,
  "players": 31,
  "capturedAt": "2026-06-16T12:00:00Z"
}

Notes

• A permissive Access-Control-Allow-Origin: * header is sent so browser dashboards can read the (read-only) data.
• Available on both Paper/Folia and Velocity.
• The server runs on daemon threads and shuts down cleanly with the plugin.