API Players

Players online and offline, what they carry, and what they've done. Every path starts with /api/v1.

Players

Endpoint	Permission	What it does
GET /players	players:read	Everyone who has played here
GET /players/online	players:read	Who is playing right now
GET /players/{player}	players:read (+ players:private)	A player's profile, state, and whereabouts, with more parts on request
PATCH /players/{player}	players:write	Change game mode, health, food, XP, flight, speed, names, and more
POST /players/{player}/kick	players:moderate	Kick a player
POST /players/{player}/message	players:write	Send a chat message, title, action bar, or sound to one player
POST /players/{player}/teleport	players:write	Teleport to coordinates, a player, or a world spawn

Inventories and ender chests

Endpoint	Permission	What it does
GET /players/{player}/enderchest	players:read (+ players:private)	Ender chest contents
DELETE /players/{player}/enderchest	players:write	Empty the whole ender chest
POST /players/{player}/enderchest/give	players:write	Add an item to the ender chest
PATCH /players/{player}/enderchest/slots/{slot}	players:write	Put an item in an ender chest slot
DELETE /players/{player}/enderchest/slots/{slot}	players:write	Empty an ender chest slot
POST /players/{player}/enderchest/slots/{slot}/take	players:write	Take some items from an ender chest slot
GET /players/{player}/inventory	players:read (+ players:private)	Main inventory, armor, and offhand with full item data
DELETE /players/{player}/inventory	players:write	Empty the whole inventory
POST /players/{player}/inventory/give	players:write	Add an item to the inventory
PATCH /players/{player}/inventory/slots/{slot}	players:write	Put an item in an inventory slot
DELETE /players/{player}/inventory/slots/{slot}	players:write	Empty an inventory slot
POST /players/{player}/inventory/slots/{slot}/take	players:write	Take some items from an inventory slot

Player data

Endpoint	Permission	What it does
GET /players/{player}/advancements	players:read	Advancements, done and in progress, with dates
POST /players/{player}/advancements/{key}	players:write	Grant an advancement
DELETE /players/{player}/advancements/{key}	players:write	Revoke an advancement
GET /players/{player}/effects	players:read	Active potion effects
POST /players/{player}/effects	players:write	Give a potion effect
DELETE /players/{player}/effects	players:write	Remove every effect
DELETE /players/{player}/effects/{effect}	players:write	Remove one effect
GET /players/{player}/permissions	players:read	Operator state, and whether the player has a permission
PATCH /players/{player}/permissions	server:console	Make a player an operator or take it away
GET /players/{player}/sessions	players:read	Play sessions WorldAPI recorded, newest first
GET /players/{player}/statistics	players:read	Every vanilla statistic, grouped by category

Notes

• GET /players/{player}?include=inventory,enderchest,effects,deaths,sessions,statistics,advancements,target adds those parts to the profile in one answer. target, for an online player and with players:private, is what they look at: the first block in their line of sight within 64 blocks with the face it hits, the nearest entity before it, the distance to each, and eye, where their eyes are and which way they look. An offline player's inventory and ender chest come from their playerdata file. deaths holds the last place the game saw them die and the newest five deaths from the history, with causes and killers.
• Changing a player's state, inventory, or effects needs them online; otherwise the answer is 409 player_offline. Statistics and advancements still read from the saved files.
• GET /players/{player}/advancements lists every advancement on the server, started or not, with its title and parent, so done=false reads as what's left to do.
• Statistics use vanilla ids, as in the stats files: custom:play_time, mined:diamond_ore, killed:zombie.

Vanished players

WorldAPI calls a player vanished while a vanish plugin (SuperVanish, PremiumVanish, Essentials, and others) sets the vanished metadata on them. To every client without players:moderate, visitors included, they look offline:

• They're missing from GET /players/online and the online counts in GET /server and GET /server/performance.
• GET /players and GET /players/{player} show them with online: false, no live state, and no position. Leaderboards mark them offline.
• Entity lists leave them out, and GET /worlds/{world}/entities/{uuid} answers 404.
• Endpoints that need an online player answer 409 player_offline, so a players:write token can't reach them either.
• GET /events and GET /players/{player}/sessions leave out what was recorded while the player was vanished.

Items

Items look the same everywhere: inventories, ender chests, containers, entity equipment, and the player.inventory topic. Next to the type, name, and enchantments, an item carries whatever applies to it:

• storedEnchantments on enchanted books;
• attributes, the modifiers the game applies, a type's defaults included;
• potion with the effects of a potion, tipped arrow, or suspicious stew;
• trim, dyedColor, and repairCost for the anvil;
• a written book's title and author, without its pages;
• a firework's flight and explosions;
• the contents of a shulker box or bundle, one level deep.

Fields that don't apply are left out, and components still holds the whole item in command syntax. Attribute amounts are what the item adds: the tooltip shows attack damage 1 higher and attack speed 4 higher, since it counts the player's base values.

GET /icons/minecraft:diamond_sword returns an item's icon as a PNG, for item grids: blocks as the game's isometric cube at 64×64, other items flat at their texture's size. It's not in the OpenAPI document. Until WorldAPI has downloaded the game client, the answer is 503 icons_loading with Retry-After.

Next: Leaderboards.