API Worlds and blocks

Worlds and what's in them: rules, the border, blocks, chunks, containers, and entities. Every path starts with /api/v1.

Worlds

Endpoint	Permission	What it does
GET /worlds	server:read	Every loaded world
GET /worlds/{world}	server:read	Time, weather, moon, border, rules, and load of one world
PATCH /worlds/{world}	world:write	Change time, weather, difficulty, spawn, or PvP
GET /worlds/{world}/border	server:read	World border
PATCH /worlds/{world}/border	world:write	Resize or move the world border
GET /spawn	server:read	Where players join for the first time and respawn without a bed
PATCH /spawn	world:write	Move the spawn point, change its world, or its respawn radius
GET /worlds/{world}/gamerules	server:read	Every game rule with its type, value, and default
PATCH /worlds/{world}/gamerules	world:write	Set game rules
GET /worlds/{world}/locate	server:read (+ players:private)	Find the nearest blocks, biomes, or structures
GET /worlds/{world}/stats	server:read	Explored area, region files, and size on disk

Blocks and chunks

Endpoint	Permission	What it does
GET /worlds/{world}/biomes/{x}/{y}/{z}	server:read	The biome at a block, with its temperature and humidity
POST /worlds/{world}/blocks/fill	world:write	Fill a box with one block
GET /worlds/{world}/blocks/{x}/{y}/{z}	server:read (+ players:private)	A block: type, state, light, biome, and contents
PUT /worlds/{world}/blocks/{x}/{y}/{z}	world:write	Set one block
GET /worlds/{world}/chunks	server:read	Loaded chunks with entity counts
GET /worlds/{world}/chunks/{chunkX}/{chunkZ}	server:read	One chunk: what lives in it, and how long players stayed
PATCH /worlds/{world}/chunks/{chunkX}/{chunkZ}	world:write	Keep a chunk loaded, or let it go
GET /worlds/{world}/highest/{x}/{z}	server:read	The highest block in a column

Containers

Endpoint	Permission	What it does
DELETE /worlds/{world}/blocks/{x}/{y}/{z}/container	world:write	Empty a whole container
POST /worlds/{world}/blocks/{x}/{y}/{z}/container/give	world:write	Add an item to a container
PATCH /worlds/{world}/blocks/{x}/{y}/{z}/container/slots/{slot}	world:write	Put an item in a container slot
DELETE /worlds/{world}/blocks/{x}/{y}/{z}/container/slots/{slot}	world:write	Empty a container slot
POST /worlds/{world}/blocks/{x}/{y}/{z}/container/slots/{slot}/take	world:write	Take some items from a container slot
GET /worlds/{world}/containers	server:read (+ players:private)	Chests, barrels, shulker boxes, and other containers near a point

Entities

Endpoint	Permission	What it does
GET /worlds/{world}/entities	server:read	Entities in a world, filtered by type, area, name, or chunk
DELETE /worlds/{world}/entities	world:write	Remove many entities by type, optionally around a point
POST /worlds/{world}/entities	world:write	Spawn entities
GET /worlds/{world}/entities/summary	server:read	How many entities there are, of which types, and where they crowd
GET /worlds/{world}/entities/{uuid}	server:read	One entity in detail
PATCH /worlds/{world}/entities/{uuid}	world:write	Change an entity: name, flags, health, position
DELETE /worlds/{world}/entities/{uuid}	world:write	Remove an entity

World effects

Endpoint	Permission	What it does
POST /worlds/{world}/explosions	world:write	Make an explosion
POST /worlds/{world}/lightning	world:write	Strike lightning
POST /worlds/{world}/particles	world:write	Show particles at a spot
POST /worlds/{world}/sounds	world:write	Play a sound at a spot

Notes

• Finding things. GET /worlds/{world}/locate?kind=block|biome|structure&target=… finds the nearest of anything. Block search (target=minecraft:diamond_ore,#minecraft:logs) reads copies of chunks that are already loaded, off the server thread, and never loads more. It needs a token whatever auth.anonymous says, because it would show ores through walls. Biomes and structures ask the world generator, so they reach unexplored land; structures take prefixes, so village finds every kind of village. Visitors locate only when they may see coordinates.
• The spawn point. GET /spawn names the world players respawn in, the point with yaw and pitch, respawnRadius (that world's respawn_radius game rule: players land at a random spot this far around the point), and spawnProtection from server.properties. PATCH /spawn takes any of world, x, y, z, yaw, pitch, and respawnRadius; the coordinates come together. {"world": "world_nether"} alone moves the respawn to that world's own point. Every world keeps a point of its own for teleports, which GET /worlds/{world} shows as spawn; only the respawn world's point is where players appear.
• Finding chests. GET /worlds/{world}/containers?x=&y=&z=&radius=&item=minecraft:diamond finds chests, barrels, shulker boxes, hoppers, and the like in loaded chunks, nearest first, with how many of the items each holds, or their five most plentiful items without item. A double chest counts once. GET /blocks/{x}/{y}/{z} shows one in full.
• Taking part of a stack. POST …/slots/{slot}/take with {"amount": n} takes items and leaves the rest of the stack as it was. It works the same in containers, inventories, and ender chests.
• What lags. GET /worlds/{world}/entities/summary counts entities per type, dropped items, villagers, named mobs, and pets, and names the ten busiest chunks with their block entities and hoppers, for the whole world or around a point. GET /worlds/{world}/chunks?sort=entities and the entity types in GET /server/performance add to it.
• Entity lists page 25 at a time by default and filter by type, name, chunk, or a point and radius.
• Clearing in bulk. DELETE /worlds/{world}/entities?type=minecraft:item clears entities, around a point if you give one. It never touches players, skips named mobs and tamed pets unless includeNamed=true, and dryRun=true only counts. limits.maxEntityRemoval caps one call.
• Items look the same everywhere: containers, inventories, entity equipment, and the player.inventory topic. See “Items” on Players.
• Gear on display. Visitors see no items that belong to a player unless privacy.anonymous.inventories is on: no container contents and no equipment on a player in GET /entities/{uuid}. Mobs and armor stands show their gear to everyone, as the game does.

Next: Players.