Players

Base: /api/players

Online and known players, actions and inventory

Handler: PlayersHandler

Endpoints

GET /api/players

List players

Returns all online players with position, world, game mode, health and stats, plus offline players known to the mod.

Response Example

[
  {
    "name": "Steve",
    "uuid": "1234...",
    "world": "default",
    "avatar": "<base64>",
    "x": 10.5,
    "y": 64.0,
    "z": -3.2,
    "gamemode": "Adventure",
    "health": 90,
    "maxHealth": 100,
    "stamina": 80,
    "maxStamina": 100,
    "mana": 0,
    "maxMana": 100,
    "defence": 12,
    "op": false,
    "online": true
  }
]

cURL

curl -X GET 'http://localhost:5550/api/players' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Reads each online player on the thread of their world; offline entries come from known_players.json.

GET /api/players/known

Known players

Lightweight list of every player that has been on the server (name, UUID, last seen).

Response Example

[
  {
    "uuid": "1234...",
    "name": "Steve",
    "online": true,
    "gamemode": "Adventure",
    "world": "default",
    "lastSeen": 1737000000000
  }
]

cURL

curl -X GET 'http://localhost:5550/api/players/known' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Reads the player tracker only, no world access. Used for dropdowns.

GET /api/players/{name}

Get player

Returns the same detailed data as the list for one online player.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Response Example

{
  "name": "Steve",
  "uuid": "1234...",
  "world": "default",
  "x": 10.5,
  "y": 64.0,
  "z": -3.2,
  "gamemode": "Adventure",
  "health": 90,
  "maxHealth": 100,
  "op": false,
  "found": true
}

cURL

curl -X GET 'http://localhost:5550/api/players/Eranio' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Finds the player in all loaded worlds and reads the data on that world thread.

GET /api/players/{name}/inventory

Get inventory

Returns hotbar, storage, armor, utility, backpack and tools with item IDs, amounts and icons.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Response Example

{
  "player": "Steve",
  "hotbar": [
    {
      "id": "hytale:sword_iron",
      "count": 1,
      "slot": 0,
      "durability": 90,
      "maxDurability": 100,
      "icon": "<base64>"
    }
  ],
  "storage": [],
  "armor": [],
  "utility": [],
  "backpack": [],
  "backpackCapacity": 18,
  "uniqueItemUsages": [
    "Upgrade_Backpack_1"
  ]
}

cURL

curl -X GET 'http://localhost:5550/api/players/Eranio/inventory' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Reads every InventoryComponent container on the world thread; icons are base64 encoded.

POST /api/players/{name}/kick

Kick player

Disconnects an online player with a message.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Request Body

Field	Type	Required	Description
`reason`	string	No	Message shown to the player, default "Kicked by admin"

Response Example

{
  "success": true,
  "player": "Steve"
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/kick' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"reason": "Please read the rules"}'

Internal Behavior

Closes the packet handler of the player directly.

POST /api/players/{name}/op

Grant OP

Gives the player operator rights.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Response Example

{
  "success": true,
  "player": "Steve"
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/op' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Writes the OP flag to permissions.json and adds the player to the hytale:Admin group.

POST /api/players/{name}/deop

Revoke OP

Removes operator rights from the player.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Response Example

{
  "success": true,
  "player": "Steve"
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/deop' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Removes the OP flag from permissions.json and the hytale:Admin group.

POST /api/players/{name}/teleport

Teleport player

Teleports the player to coordinates in their current world.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Request Body

Field	Type	Required	Description
`x`	number	Yes	Target X
`y`	number	Yes	Target Y
`z`	number	Yes	Target Z

Response Example

{
  "success": true,
  "player": "Steve",
  "x": 10.0,
  "y": 64.0,
  "z": -3.0
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/teleport' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"x": 120.5, "y": 80, "z": -45.5}'

Internal Behavior

Adds a Teleport component on the world thread and keeps the head rotation.

POST /api/players/{name}/give

Give item

Adds an item to the inventory, hotbar first.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Request Body

Field	Type	Required	Description
`item`	string	Yes	Item ID (alias itemId)
`amount`	integer	No	Amount 1 to 999, default 1 (alias quantity)

Response Example

{
  "success": true,
  "item": "hytale:sword_iron",
  "amount": 1
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/give' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"item": "Weapon_Sword_Iron", "amount": 1}'

Internal Behavior

Builds an ItemStack on the world thread; fails with an error if the inventory is full.

POST /api/players/{name}/heal

Heal player

Restores the player to full health.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Response Example

{
  "success": true,
  "player": "Steve"
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/heal' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Raises the Health stat to its maximum on the world thread.

POST /api/players/{name}/gamemode

Set game mode

Switches the player between Adventure and Creative.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Request Body

Field	Type	Required	Description
`gamemode`	string	Yes	adventure or creative

Response Example

{
  "success": true,
  "gamemode": "creative"
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/gamemode' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"gamemode": "creative"}'

Internal Behavior

Calls Player.setGameMode on the world thread.

POST /api/players/{name}/inventory/clear

Clear inventory

Empties hotbar, storage, armor, utility, backpack and tools.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Response Example

{
  "success": true,
  "player": "Steve"
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/inventory/clear' \
  -H 'X-Admin-Token: YOUR_TOKEN'

Internal Behavior

Clears every container on the world thread.

POST /api/players/{name}/inventory/slot

Set slot

Places an item into a specific slot and replaces what was there.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Request Body

Field	Type	Required	Description
`item`	string	Yes	Item ID (alias itemId)
`amount`	integer	No	Amount 1 to 999, default 1
`section`	string	No	hotbar, storage, armor, utility, backpack or tools, default storage
`slot`	integer	No	Slot index, default 0

Response Example

{
  "success": true,
  "item": "hytale:sword_iron",
  "amount": 1
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/inventory/slot' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"item": "Food_Bread", "amount": 16, "section": "hotbar", "slot": 2}'

Internal Behavior

Calls setItemStackForSlot on the chosen container.

POST /api/players/{name}/inventory/slot/remove

Clear slot

Removes the item from one slot.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Request Body

Field	Type	Required	Description
`section`	string	No	Container, default storage
`slot`	integer	No	Slot index, default 0

Response Example

{
  "success": true,
  "section": "storage",
  "slot": 0
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/inventory/slot/remove' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"section": "storage", "slot": 5}'

Internal Behavior

Calls removeItemStackFromSlot on the chosen container.

POST /api/players/{name}/inventory/slot/swap

Swap slots

Swaps two slots, also between containers (for example storage and hotbar).

Parameters

Name	Type	Required	Description
`name`	string	Yes	Player name

Request Body

Field	Type	Required	Description
`fromSection`	string	No	Source container, default storage
`fromSlot`	integer	No	Source slot, default 0
`toSection`	string	No	Target container, default storage
`toSlot`	integer	No	Target slot, default 0

Response Example

{
  "success": true
}

cURL

curl -X POST 'http://localhost:5550/api/players/Eranio/inventory/slot/swap' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"fromSection": "storage", "fromSlot": 3, "toSection": "hotbar", "toSlot": 0}'

Internal Behavior

Swaps the ItemStacks on the world thread.