Contents of the docs
minecraft-api · Docs
HTTP API
All endpoints of minecraft-api with fields and example responses – players, dimensions, entities and loaded chunks.
All endpoints answer GET with JSON (Content-Type: application/json). There are no parameters, no pagination and no
cache: every request reads the current state of the server. Unknown paths return the same response as /.
| Path | Content |
|---|---|
/ |
players and dimensions in one response |
/players |
online players |
/dimensions |
dimensions with spawn point and world border |
/entities |
all entities of all dimensions |
/chunks/active |
all loaded chunks of all dimensions |
/
Combines /players and /dimensions:
{
"players": { "max": 20, "players": { } },
"dimensions": [ ]
}/players
max is the maximum number of players of the server, players an object keyed by UUID.
{
"max": 20,
"players": {
"0f6a…-…": {
"uuid": "0f6a…-…",
"name": "Steve",
"dimension": "minecraft:overworld",
"x": -112.5,
"y": 71.0,
"z": 48.3,
"yHeadRot": 93.4,
"armor": 20,
"health": 20.0,
"gameMode": 0,
"gameModeName": "survival",
"isInvisible": false,
"experienceLevel": 30
}
}
}gameMode is the number of the game mode: 0 survival, 1 creative, 2 adventure, 3 spectator. armor are the
armor points (0 to 30), health the health points (20 = ten hearts).
/dimensions
[
{
"id": "minecraft:overworld",
"spawn": { "x": 0, "y": 64, "z": 0 },
"border": {
"x": { "min": -29999984.0, "max": 29999984.0 },
"z": { "min": -29999984.0, "max": 29999984.0 },
"center": { "x": 0.0, "z": 0.0 }
}
}
]Dimensions from other mods or datapacks show up with their own ID.
/entities
A list of all entities the server currently has loaded – including players, items, experience orbs, minecarts and armor stands.
[
{
"uuid": "5b2c…-…",
"type": "minecraft:zombie",
"category": "monster",
"name": "Zombie",
"customName": null,
"dimension": "minecraft:overworld",
"x": -98.7,
"y": 63.0,
"z": 51.2,
"born": { "at": { "timestamp": 1765530000000, "gameTime": 1834210 } },
"tags": [ ],
"chunk": { "id": "minecraft:overworld[-112 | 48] - [-97 | 63]", "dimension": "minecraft:overworld", "status": "ENTITY_TICKING", "position": { "min": { "x": -112, "z": 48 }, "max": { "x": -97, "z": 63 } } }
},
{
"uuid": "a91e…-…",
"type": "minecraft:item",
"category": "item",
"name": "Item",
"item": { "name": "Rotten Flesh", "type": "minecraft:rotten_flesh", "count": 3 }
}
]The second example is shortened; items have the same fields as every other entity plus item.
| Field | Meaning |
|---|---|
type |
registry ID of the entity |
category |
Minecraft mob category: monster, creature, ambient, axolotls, underground_water_creature, water_creature, water_ambient, misc – item for items |
name |
display name of the type in the server's language |
customName |
name given with a name tag, or null |
born.at |
first appearance in the world: timestamp in milliseconds since 1970, gameTime in ticks |
tags |
tags from /tag |
chunk |
the chunk the entity stands in, in the format of /chunks/active |
born is stored in the entity's data when it first joins the world, so it survives restarts. Entities that existed
before the mod was installed get the time they are next loaded.
/chunks/active
All chunks the server keeps in memory:
[
{
"id": "minecraft:the_nether[16 | -32] - [31 | -17]",
"dimension": "minecraft:the_nether",
"status": "BLOCK_TICKING",
"position": { "min": { "x": 16, "z": -32 }, "max": { "x": 31, "z": -17 } }
}
]position holds the block coordinates of both corners. status tells how much is happening in the chunk:
| Status | Meaning |
|---|---|
ENTITY_TICKING |
fully active: mobs move, farms run |
BLOCK_TICKING |
blocks and redstone run, entities stand still |
FULL |
loaded, but nothing is processed |
INACCESSIBLE |
loading or just unloaded |
UNKNOWN |
the chunk is no longer in memory |
Example
Count all monsters in the overworld with jq:
curl -s http://localhost:9874/entities \
| jq '[.[] | select(.dimension == "minecraft:overworld" and .category == "monster")] | length'