REST API

Everything a client can call lives under /api/v1. This page gives the rules every endpoint follows; the pages under “API” in the sidebar list the endpoints by area.

Your server documents itself: /api/v1/docs shows every endpoint with every field, and /api/v1/openapi.json is the same as an OpenAPI 3.1 document for code generators. A copy sits in the repository as docs/openapi.json.

The areas

Page	What it covers
Server	The server, its load, the host, plugins, console commands, broadcasts, saves, restarts, the whitelist, operators, bans, and recipes
Worlds and blocks	Worlds, game rules, the border, locate, blocks, chunks, containers, entities, and world effects
Players	Profiles, inventories, ender chests, effects, statistics, advancements, sessions, and moderation
Leaderboards	Presets, any vanilla statistic, and everyone's totals
Events	The event history
Files	Server and plugin configs and logs
Access control	Tokens, groups, panel accounts, sign-in, and the audit log
WebSocket	The live feed
Extensions	Other plugins' data
Java scripts	Running Java on the server

Conventions

• JSON in camelCase. Times are ISO-8601; where ticks matter, they come along (dayTime, fullTime, durationTicks).
• Players go by UUID or name; worlds by folder name (world_nether) or key (minecraft:the_nether).
• GET reads, POST creates or runs an action, PATCH changes properties, PUT sets a block or writes a file, DELETE removes.
• Lists page with limit and cursor: pass the nextCursor of one page to get the next. Lists with a total answer limit=0 with the total alone, for a quick count.
• Write bodies are strict: an unknown field is a 400, not a silent no-op. Only the fields you send change.
• Each operation names the permission it needs, listed on each page. “(+ players:private)” means the private parts of the answer need that permission too, or the matching privacy.anonymous switch for visitors.

Authentication

Send a token as Authorization: Bearer <token>. Without one, a client reads only what auth.anonymous.endpoints opens. Tokens and permissions explains tokens and groups.

Errors

Errors look the same everywhere, with the matching HTTP status:

{ "error": { "code": "player_offline", "message": "Steve isn't online" } }

Common ones: 400 for a bad request, 401 without a valid token, 403 without the permission, 404 for something that isn't there, 409 player_offline when a change needs the player online, 413 for a body over http.maxBodyBytes, 429 past the rate limit, and 503 when the server thread was too busy to answer in time.

Examples

Who's online, for a status page. No token needed:

$ curl -s https://mc.example.com/worldapi/api/v1/players/online
{"count":2,"max":20,"players":[{"name":"Steve","world":"world","gameMode":"survival","health":20.0,"ping":38,…},…]}

A leaderboard. Presets like playtime, diamonds, and mobs, or any vanilla statistic:

curl -s 'https://mc.example.com/worldapi/api/v1/leaderboards/playtime?limit=3'
curl -s 'https://mc.example.com/worldapi/api/v1/leaderboards/killed:pig'

What lags. One request counts entities per type and names the busiest chunks:

curl -s -H "Authorization: Bearer $TOKEN" https://mc.example.com/worldapi/api/v1/worlds/world/entities/summary

What the log said before the crash. Search yesterday's log, with two lines around each match:

curl -s -H "Authorization: Bearer $TOKEN" \
  'https://mc.example.com/worldapi/api/v1/files/read?path=logs/2026-10-18-1.log.gz&grep=exception&context=2'

A config change by key, comments kept, with a backup of the old file:

curl -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  https://mc.example.com/worldapi/api/v1/files/set \
  -d '{"path": "server.properties", "values": {"view-distance": 12}}'

A live feed in the browser. See WebSocket.