HTTP API

All endpoints return application/json. No authentication is required.

GET `/`

Serves the HTML dashboard.

GET `/bots`

Returns a summary list of all running bots.

Response

[
  {
    "id": 1,
    "username": "string",
    "status": "in_world",
    "world": "string",
    "pos_x": 0.0,
    "pos_y": 0.0,
    "gems": 0,
    "ping_ms": 0
  }
]

POST `/bots`

Spawns a new bot.

Request Body

{
  "username": "string",
  "password": "string",
  "proxy_host": "string",
  "proxy_port": 1080,
  "proxy_username": "string",
  "proxy_password": "string"
}

proxy_host and proxy_port are required together to enable SOCKS5 proxy. Username/password are optional.

Response

{ "id": 1 }

DELETE `/bots/{id}`

Stops and removes a bot.

Status	Meaning
`204`	Stopped successfully
`404`	Bot not found

GET `/bots/{id}/state`

Returns the full state of a bot.

Response

{
  "status": "in_world",
  "world_name": "string",
  "pos_x": 0.0,
  "pos_y": 0.0,
  "world_width": 100,
  "world_height": 60,
  "tiles": [
    {
      "fg_item_id": 0,
      "bg_item_id": 0,
      "flags": 0,
      "tile_type": { "type": "Basic" }
    }
  ],
  "players": [
    {
      "net_id": 0,
      "name": "string",
      "pos_x": 0.0,
      "pos_y": 0.0,
      "country": "us"
    }
  ],
  "objects": [
    {
      "uid": 0,
      "item_id": 0,
      "x": 0.0,
      "y": 0.0,
      "count": 1
    }
  ],
  "inventory": [
    {
      "item_id": 0,
      "amount": 0,
      "is_active": false,
      "action_type": 0
    }
  ],
  "gems": 0,
  "console": ["string"],
  "ping_ms": 0,
  "delays": {
    "place_ms": 500,
    "walk_ms": 500
  },
  "track_info": {
    "level": 0,
    "grow_id": 0,
    "install_date": 0,
    "global_playtime": 0,
    "awesomeness": 0
  }
}

track_info is null until the server sends account data after login.

Status	Meaning
`200`	OK
`404`	Bot not found

POST `/bots/{id}/cmd`

Sends a command to a bot.

Status	Meaning
`204`	Command sent
`404`	Bot not found

All commands use a tagged union with a "type" field.

`move`

Move the bot to a pixel position.

{ "type": "move", "x": 0.0, "y": 0.0 }

`walk_to`

Pathfind to a tile position.

{ "type": "walk_to", "x": 0, "y": 0 }

`run_script`

Run a Lua script on the bot.

{ "type": "run_script", "content": "string" }

`stop_script`

Stop the currently running script.

{ "type": "stop_script" }

`wear`

Equip an item.

{ "type": "wear", "item_id": 0 }

`unwear`

Unequip an item.

{ "type": "unwear", "item_id": 0 }

`drop`

Drop items into the world.

{ "type": "drop", "item_id": 0, "count": 1 }

`trash`

Permanently delete items.

{ "type": "trash", "item_id": 0, "count": 1 }

`set_delays`

Configure action delays in milliseconds.

{ "type": "set_delays", "place_ms": 500, "walk_ms": 500 }

GET `/items/names`

Returns a flat map of all item IDs to their names. Useful for quick lookups without pagination.

Response

{
  "0": "x",
  "2": "y",
  "8": "z"
}

Keys are item IDs as strings (standard JSON object key behaviour). No query parameters.

GET `/items`

Paginated search through the item database.

Query Parameters

Param	Type	Default	Description
`page`	integer	`1`	Page number (1-indexed)
`q`	string	`""`	Search by item ID (exact) or name (substring, case-insensitive)

Response

{
  "items": [
    {
      "id": 0,
      "name": "string",
      "flags": 0,
      "action_type": 0,
      "material": 0,
      "texture_file_name": "string",
      "texture_hash": 0,
      "visual_effect": 0,
      "collision_type": 0,
      "rarity": 0,
      "max_item": 0,
      "grow_time": 0,
      "base_color": 0,
      "overlay_color": 0,
      "clothing_type": 0
    }
  ],
  "total": 0,
  "page": 1,
  "page_size": 50
}

50 items per page.

HTTP API

On this page