Worlds

Base: /api/worlds

Create, load, park, reset and delete permanent worlds

Handler: WorldsHandler

Endpoints

GET /api/worlds

Worlds overview

Returns loaded worlds (default first) with type, owner, settings and size, plus unloaded, parked and trashed worlds and the available generators.

Response Example

{
  "default": "default",
  "worlds": [
    {
      "name": "default",
      "kind": "server",
      "owner": null,
      "display_name": null,
      "default": true,
      "players": 1,
      "player_names": [
        "Steve"
      ],
      "generator": "Hytale",
      "seed": "12345",
      "pvp": true,
      "fall_damage": true,
      "npc_spawning": true,
      "npc_frozen": false,
      "time_paused": false,
      "game_mode": "Adventure",
      "size_mb": 128.4
    }
  ],
  "unloaded": [
    {
      "name": "arena",
      "kind": "server",
      "owner": null,
      "size_mb": 10.2
    }
  ],
  "parked": [
    {
      "name": "pw-1234abcd-1",
      "kind": "player",
      "owner": "Steve",
      "size_mb": 5.1
    }
  ],
  "trash": [
    {
      "folder": "oldworld_20260101_010000",
      "size_mb": 2.0
    }
  ],
  "generators": [
    "Hytale",
    "Flat",
    "Void"
  ]
}

cURL

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

Internal Behavior

Combines the universe, the folders universe/worlds, worlds-parked and worlds-trash and worlds-meta.json. Instances are left out.

POST /api/worlds/create

Create world

Creates a permanent world. Hytale loads it on every start.

Request Body

Field	Type	Required	Description
`name`	string	Yes	a-z, 0-9, _ and -, 2 to 32 characters
`generator`	string	No	Hytale (default), Flat or Void
`kind`	string	No	server (default) or player
`owner`	string	No	Owner shown in the panel
`display_name`	string	No	Display name
`game_mode`	string	No	Adventure or Creative
`pvp`	boolean	No	PvP
`fall_damage`	boolean	No	Fall damage
`npc_spawning`	boolean	No	NPC spawning
`npc_frozen`	boolean	No	Freeze NPCs
`time_paused`	boolean	No	Pause time

Response Example

{
  "success": true,
  "world": "arena",
  "generator": "Hytale"
}

cURL

curl -X POST 'http://localhost:5550/api/worlds/create' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "farmwelt", "generator": "Hytale", "display_name": "Farmwelt", "pvp": false}'

Internal Behavior

Calls Universe.addWorld (up to 60 seconds), applies the settings and stores type and owner.

POST /api/worlds/load

Load world

Loads an unloaded world.

Request Body

Field	Type	Required	Description
`name`	string	Yes	World folder in universe/worlds

Response Example

{
  "success": true,
  "world": "arena"
}

cURL

curl -X POST 'http://localhost:5550/api/worlds/load' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "farmwelt"}'

Internal Behavior

Calls Universe.loadWorld.

POST /api/worlds/unload

Unload world

Saves and unloads a world; the folder stays.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Loaded world (not the default world, no players inside)

Response Example

{
  "success": true,
  "world": "arena"
}

cURL

curl -X POST 'http://localhost:5550/api/worlds/unload' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "farmwelt"}'

Internal Behavior

Turns off deleteOnRemove and calls Universe.removeWorld.

POST /api/worlds/delete

Move world to trash

Moves a world to the trash; nothing is deleted yet.

Request Body

Field	Type	Required	Description
`name`	string	Yes	World (loaded, unloaded or parked)

Response Example

{
  "success": true,
  "world": "arena",
  "folder": "arena_20260101_010000"
}

cURL

curl -X POST 'http://localhost:5550/api/worlds/delete' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "farmwelt"}'

Internal Behavior

Unloads if needed and moves the folder to universe/worlds-trash/<name>_<date>.

POST /api/worlds/restore

Restore world

Moves a world back from the trash and loads it.

Request Body

Field	Type	Required	Description
`folder`	string	Yes	Folder name in the trash

Response Example

{
  "success": true,
  "world": "arena"
}

cURL

curl -X POST 'http://localhost:5550/api/worlds/restore' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"folder": "farmwelt_20261013_101500"}'

Internal Behavior

Removes the date suffix and calls Universe.loadWorld.

POST /api/worlds/purge

Delete world permanently

Deletes a trash entry from disk.

Request Body

Field	Type	Required	Description
`folder`	string	Yes	Folder name in the trash

Response Example

{
  "success": true,
  "folder": "arena_20260101_010000"
}

cURL

curl -X POST 'http://localhost:5550/api/worlds/purge' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"folder": "farmwelt_20261013_101500"}'

Internal Behavior

Deletes the folder recursively and removes the type entry if no other copy exists.

POST /api/worlds/park

Park world

Unloads a world and moves it to universe/worlds-parked, so Hytale does not load it on start.

Request Body

Field	Type	Required	Description
`name`	string	Yes	World (loaded or unloaded)

Response Example

{
  "success": true,
  "world": "arena"
}

cURL

curl -X POST 'http://localhost:5550/api/worlds/park' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "lasttest-001"}'

Internal Behavior

Unloads if needed and moves the folder.

POST /api/worlds/unpark

Unpark world

Moves a parked world back and loads it.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Parked world
`load`	boolean	No	Load right away, default true

Response Example

{
  "success": true,
  "world": "arena"
}

cURL

curl -X POST 'http://localhost:5550/api/worlds/unpark' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "lasttest-001"}'

Internal Behavior

Moves the folder to universe/worlds and calls Universe.loadWorld.

POST /api/worlds/mark

Set world type

Marks a world as server world or player world with owner (for the panel).

Request Body

Field	Type	Required	Description
`name`	string	Yes	World
`kind`	string	No	server (default) or player
`owner`	string	No	Owner

Response Example

{
  "success": true,
  "world": "arena",
  "kind": "server"
}

cURL

curl -X POST 'http://localhost:5550/api/worlds/mark' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "lasttest-001", "kind": "player", "owner": "Eranio"}'

Internal Behavior

Writes worlds-meta.json.

POST /api/worlds/default

Set default world

Makes a world the default world of the server.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Loaded world

Response Example

{
  "success": true,
  "world": "default"
}

cURL

curl -X POST 'http://localhost:5550/api/worlds/default' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "default"}'

Internal Behavior

Changes the default world in the server config.

POST /api/worlds/settings

World settings

Changes settings of a loaded world; only the given fields change.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Loaded world
`display_name`	string	No	Display name, empty removes it
`game_mode`	string	No	Adventure or Creative
`pvp`	boolean	No	PvP
`fall_damage`	boolean	No	Fall damage
`npc_spawning`	boolean	No	NPC spawning
`npc_frozen`	boolean	No	Freeze NPCs
`time_paused`	boolean	No	Pause time

Response Example

{
  "success": true,
  "world": "arena"
}

cURL

curl -X POST 'http://localhost:5550/api/worlds/settings' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "farmwelt", "pvp": true, "time_paused": false}'

Internal Behavior

Applies the fields to WorldConfig on the world thread.

POST /api/worlds/reset

Reset world

Deletes a world and generates it again with a new seed (farm world). Generator, settings and display name stay.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Loaded world, not the default world, no players inside
`move_warps`	boolean	No	Move warps of this world to the new spawn, default true

Response Example

{
  "success": true,
  "world": "arena",
  "seed": "67890",
  "warps_moved": 2,
  "spawn": "0, 64, 0"
}

cURL

curl -X POST 'http://localhost:5550/api/worlds/reset' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name": "farmwelt", "move_warps": true}'

Internal Behavior

Removes the world with deleteOnRemove, creates it again and moves the warps to the new spawn.

POST /api/worlds/send

Send player to world

Teleports a player to the spawn of another world.

Request Body

Field	Type	Required	Description
`player`	string	Yes	Online player
`world`	string	Yes	Loaded target world

Response Example

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

cURL

curl -X POST 'http://localhost:5550/api/worlds/send' \
  -H 'X-Admin-Token: YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"player": "Eranio", "world": "farmwelt"}'

Internal Behavior

Writes a teleport history entry and adds a Teleport component.