🌍 Map & Environment API¶

This section covers interacting with the physical game world, weather, buildings, and zones.

Map Controller¶

Focuses on the Local map selected by map_id. This handles the physical terrain and conditions of the colony's immediate area.

Scope

This controller deals with the environment, not the entities within it. For Pawns or Items, see their respective controllers.

Capabilities:

Change local weather.
Query map size and boundaries.
Modify terrain (set floors, clear debris).

GET


/api/v1/map/things

¶

Returns a comprehensive list of all objects (things) present on the current map.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/map/things?map_id=0

Response:

{
    "success": true,
    "data": [
        {
            "thing_id": 2328,
            "def_name": "ChunkGranite",
            "label": "granite chunk",
            "categories": [
                "StoneChunks"
            ],
            "position": {
                "x": 41,
                "y": 0,
                "z": 1
            },
            "stack_count": 1,
            "market_value": 0.0,
            "is_forbidden": false,
            "quality": -1,
            "hit_points": 300,
            "max_hit_points": 300
        },
        {
            "thing_id": 4895,
            "def_name": "MealSurvivalPack",
            "label": "packaged survival meal",
            "categories": [
                "FoodMeals"
            ],
            "position": {
                "x": 13,
                "y": 0,
                "z": 62
            },
            "stack_count": 1,
            "market_value": 24.0,
            "is_forbidden": true,
            "quality": -1,
            "hit_points": 50,
            "max_hit_points": 50
        },
        <...>
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

GET


/api/v1/maps

¶

Retrieves a list of all currently loaded maps in the game session.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/maps

Response:

{
    "success": true,
    "data": [
        {
        "id": 0,
        "index": 0,
        "seed": 16622162,
        "faction_id": "14",
        "is_player_home": true,
        "is_pocket_map": false,
        "is_temp_incident_map": false,
        "size": "(150, 1, 150)"
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:38:45.9289233Z"
}

GET


/api/v1/map/pawns

¶

Gets a list of all colonists/pawns present on the specified map. Returns key status information like health, mood, and position for each.

curl --request GET \
--url 'http://localhost:8765/api/v1/map/pawns?mapId=0'

Response:

{
    "success": true,
    "data": [
        {
            "id": 148,
            "name": "Val",
            "gender": "Female",
            "age": 25,
            "health": 1.0,
            "mood": 0.85,
            "hunger": 0.2,
            "position": {
                "x": 102,
                "y": 0,
                "z": 115
            }
        },
        {
            "id": 149,
            "name": "Stumpy",
            "gender": "Male",
            "age": 42,
            "health": 0.65,
            "mood": 0.4,
            "hunger": 0.8,
            "position": {
                "x": 105,
                "y": 0,
                "z": 112
            }
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-31T14:30:00.0000000Z"
}

GET


/api/v1/map/terrain

¶

Returns the full terrain and floor grid data for the specified map.

Note on Data Format: To optimize bandwidth, this endpoint uses Run-Length Encoding (RLE) and Palette Mapping.

palette: A list of unique terrain definitions (e.g., "Soil", "WaterDeep").
grid: A compressed list of integers representing the map cells. Format is pairs of [count, palette_index].

Example decoding: A grid [10, 0, 5, 2] means "10 cells of palette[0], followed by 5 cells of palette[2]".

Example:

curl --request GET \
--url http://localhost:8765/api/v1/map/terrain?map_id=0

Response:

{
    "success": true,
    "data": {
        "width": 250,
        "height": 250,
        "palette": [
            "Soil",
            "Gravel",
            "SoilRich",
            "WaterDeep"
        ],
        "grid": [
            22,
            0,
            5,
            1,
            500,
            0,
            10,
            3
        ],
        "floor_palette": [
            "WoodPlankFloor",
            "TileSandstone"
        ],
        "floor_grid": [
            62400,
            0,
            50,
            1,
            50,
            2
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-14T13:12:28.8217513Z"
}

GET


/api/v1/map/things-at

¶

Returns a list of things located at a specific single cell coordinate.

Note: Unlike standard GET requests, this endpoint requires a JSON body containing the coordinates.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/map/things-at \
--header 'Content-Type: application/json' \
--data '{
    "map_id": 0,
    "position": { "x": 15, "y": 0, "z": 25 }
}'

Request Body:

{
    "map_id": 0,
    "position": {
        "x": 15,
        "y": 0,
        "z": 25
    }
}

Response:

{
    "success": true,
    "data": [
        {
            "thing_id": 4895,
            "def_name": "MealSurvivalPack",
            "label": "packaged survival meal",
            "position": { "x": 15, "y": 0, "z": 25 },
            "stack_count": 10
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-14T13:40:00.000Z"
}

GET


/api/v1/map/things/radius

¶

Returns a list of all things found within a specified radius around a center point. Useful for finding nearby resources or enemies.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/map/things/radius?map_id=0&x=120&z=120&radius=10"

Response:

{
    "success": true,
    "data": [
        {
            "thing_id": 2328,
            "def_name": "ChunkGranite",
            "label": "granite chunk",
            "position": { "x": 121, "y": 0, "z": 119 },
            "stack_count": 1
        },
        {
            "thing_id": 5012,
            "def_name": "Steel",
            "label": "steel",
            "position": { "x": 118, "y": 0, "z": 122 },
            "stack_count": 35
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-14T13:42:00.000Z"
}

GET


/api/v1/map/ore

¶

Returns a compressed dictionary of all ore deposits on the map.

Structure: * Keys are the ore definition names (e.g., "MineableSteel"). * cells contains the flattened map indices of the ore. * hp contains the current health of the ore block at the corresponding index (parallel arrays).

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/map/ore?map_id=0"

Response:

{
    "success": true,
    "data": {
        "map_width": 250,
        "ores": {
            "MineableSteel": {
                "max_hp": 1500,
                "cells": [
                    12500,
                    12501,
                    12502
                ],
                "hp": [
                    1500,
                    1500,
                    850
                ]
            },
            "MineableGold": {
                "max_hp": 500,
                "cells": [
                    3005
                ],
                "hp": [
                    500
                ]
            }
        }
    },
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

GET


/api/v1/map/fog-grid

¶

Retrieves the visibility (fog of war) grid for the current map.

The fog_data is a flat string representation of the grid where Index = (z * Width) + x.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/map/fog-grid?map_id=0"

Response:

{
    "success": true,
    "data": {
        "map_id": 0,
        "width": 250,
        "height": 250,
        "fog_data": "AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyAhIiMkJSYnKCkqKywtLi8wMTIzNDU2Nzg5Ojs8PT4/QEFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFlaW1xdXl9gYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXp7fH1+fw=="
    },
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

GET


/api/v1/map/plants

¶

Returns a list of all plants located on the specified map. This includes wild plants (trees, bushes, grass) and sown crops.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/map/plants?map_id=0"

Response:

{
    "success": true,
    "data": [
        {
            "thing_id": 1024,
            "def_name": "Plant_TreeOak",
            "label": "oak tree",
            "position": { "x": 45, "y": 0, "z": 88 },
            "growth": 0.85
        },
        {
            "thing_id": 1025,
            "def_name": "Plant_Potato",
            "label": "potato plant",
            "position": { "x": 50, "y": 0, "z": 50 },
            "growth": 0.45
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-14T14:12:00.000Z"
}

GET


/api/v1/map/weather

¶

Retrieves the current weather conditions and temperature for the currently active map (the map the player is viewing).

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/map/weather?map_id=0'

Response:

{
    "success": true,
    "data": {
        "weather": "Rain",
        "temperature": 19.7876511
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:39:54.5380426Z"
}

GET


/api/v1/map/animals

¶

Retrieves a list of all animals currently present on the active map. This includes both wild animals and tamed/owned animals (pets, livestock, caravan animals).

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/map/animals?map_id=0'

Response:

{
    "success": true,
    "data": [
        {
        "id": 3633,
        "name": "Colin",
        "def": "Yak",
        "faction": "PlayerColony",
        "position": {
            "x": 67,
            "y": 119,
            "z": 0
        },
        "pregnant": false
        },
        {
        "id": 8547,
        "name": "Hare",
        "def": "Hare",
        "position": {
            "x": 50,
            "y": 40,
            "z": 0
        },
        "pregnant": false
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:41:34.3358819Z"
}

GET


/api/v1/map/zones

¶

Retrieves a list of all defined zones and areas on the active map. Zones are player-designated and areas are specific purposes layouts, such as roof build, clear pollution, etc.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/map/zones?map_id=0'

Response:

{
    "success": true,
    "data": {
        "zones": [],
        "areas": [
            {
                "id": 0,
                "cells_count": 0,
                "label": "Home",
                "base_label": "Home",
                "type": "Area_Home"
            },
            {
                "id": 1,
                "cells_count": 0,
                "label": "Build roof",
                "base_label": "Build roof",
                "type": "Area_BuildRoof"
            },
            {
                "id": 2,
                "cells_count": 0,
                "label": "No roof",
                "base_label": "No roof",
                "type": "Area_NoRoof"
            },
            {
                "id": 3,
                "cells_count": 0,
                "label": "Snow clear",
                "base_label": "Snow clear",
                "type": "Area_SnowClear"
            },
            {
                "id": 4,
                "cells_count": 0,
                "label": "Pollution clear",
                "base_label": "Pollution clear",
                "type": "Area_PollutionClear"
            },
            {
                "id": 5,
                "cells_count": 0,
                "label": "Area 1",
                "base_label": "Area 1",
                "type": "Area_Allowed"
            }
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:42:50.3515476Z"
}

GET


/api/v1/map/building/info

¶

Retrieves detailed information about a specific building on the active map, given its unique identifier.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/building/info?id=51058'

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:53:16.733319Z"
}

POST


/api/v1/map/weather/change

¶

Manually changes the current weather conditions on the active map.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/map/weather/change?map_id=0&name=Clear'

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:53:16.733319Z"
}

GET


/api/v1/map/power/info

¶

Provides detailed information about the power grid on the current map, including generators, batteries, consumers, network balance, and power flow status.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/map/power/info?map_id=0

Response:

{
    "success": true,
    "data": {
        "produce_power_buildings": [],
        "consume_power_buildings": [],
        "store_power_buildings": [],
        "current_power": 0,
        "total_possible_power": 0,
        "currently_stored_power": 0,
        "total_power_storage": 0,
        "total_consumption": 0,
        "consumption_power_on": 0
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:48:05.7377482Z"
}

GET


/api/v1/map/creatures/summary

¶

Returns a summarized count and classification of all creatures (pawns) on the current map.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/creatures/summary?map_id=0

Response:

{
    "success": true,
    "data": {
        "colonists_count": 3,
        "prisoners_count": 0,
        "enemies_count": 0,
        "animals_count": 5,
        "insectoids_count": 0,
        "mechanoids_count": 0
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:49:21.2287056Z"
}

GET


/api/v1/map/farm/summary

¶

Retrieves a summary of all farming activities on the current map, including planted crops, growth stages, soil fertility, and expected yield.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/farm/summary?map_id=0

Response:

{
    "success": true,
    "data": {
        "total_growing_zones": 0,
        "total_plants": 0,
        "total_expected_yield": 0,
        "total_infected_plants": 0,
        "growth_progress_average": 0.0,
        "crop_types": []
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:52:41.9403791Z"
}

POST


/api/v1/map/zone/growing

¶

Returns detailed information about all growing zones on the map, including their plant types, growth progress, and zone settings.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/zone/growing?map_id=0

Response:

{
    "success": true,
    "data": {
        "zone": {
        "id": 0,
        "cells_count": 24,
        "label": "Growing zone 1",
        "base_label": "Growing zone"
        },
        "plant_def_name": "Plant_Potato",
        "plant_count": 2,
        "def_expected_yield": 0,
        "expected_yield": 0,
        "infected_count": 0,
        "growth_progress": 0.5825427,
        "is_sowing": true,
        "soil_type": "Soil",
        "fertility": 1.0,
        "has_dying": false,
        "has_dying_from_pollution": false,
        "has_dying_from_no_pollution": false
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:53:31.8379705Z"
}

GET


/api/v1/map/rooms

¶

Retrieves a list of all colonists in the player's faction, including their skills, traits, health, mood, and current activities.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/rooms?map_id=0

Response:

{
    "success": true,
    "data": {
        "rooms": [
        {
            "id": 5,
            "role_label": "none",
            "temperature": 4.217273,
            "cells_count": 0,
            "touches_map_edge": false,
            "is_prison_cell": false,
            "is_doorway": false,
            "open_roof_count": 0,
            "contained_beds_ids": []
        },
        {
            "id": 61,
            "role_label": "bedroom",
            "temperature": 4.217273,
            "cells_count": 6,
            "touches_map_edge": false,
            "is_prison_cell": false,
            "is_doorway": false,
            "open_roof_count": 6,
            "contained_beds_ids": [
            8408
            ]
        }
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:57:48.1578638Z"
}

GET


/api/v1/map/buildings

¶

Retrieves a comprehensive list of all buildings and structures present on the active map.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/map/buildings?map_id=0'

Response:

{
    "success": true,
    "data": [
        {
            "id": 8880,
            "def": "Turret_MiniTurret",
            "label": "steel mini-turret",
            "position": {
                "x": 60,
                "y": 0,
                "z": 86
            },
            "type": "Building_TurretGun"
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:46:33.2115192Z"
}

POST


/api/v1/map/destroy/corpses

¶

Destroys all corpses on the map.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/destroy/corpses

POST


/api/v1/map/destroy/forbidden

¶

Destroys all forbidden items on the map.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/destroy/forbidden

POST


/api/v1/map/destroy/rect

¶

Destroys all things within a specified rectangle on the map.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/destroy/rect \
--header 'content-type: application/json' \
--data '{
    "map_id": 0,
    "point_a": {"x": 7, "y": 0, "z": 7},
    "point_b": {"x": 32, "y": 0, "z": 32}
}'

Request:

{
    "map_id": 0,
    "point_a": {"x": 7, "y": 0, "z": 7},
    "point_b": {"x": 32, "y": 0, "z": 32}
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-31T11:04:27.9729153Z"
}

POST


/api/v1/map/repair/positions

¶

Repairs items placed on provided list of positions.

POST


/api/v1/map/repair/rect

¶

Repairs all repairable items within a specified rectangle on the map.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/repair/rect \
--header 'content-type: application/json' \
--data '{
    "map_id": 0,
    "point_a": {"x": 7, "y": 0, "z": 7},
    "point_b": {"x": 32, "y": 0, "z": 32}
}'

Request:

{
    "map_id": 0,
    "point_a": {"x": 7, "y": 0, "z": 7},
    "point_b": {"x": 32, "y": 0, "z": 32}
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-31T11:04:27.9729153Z"
}

POST


/api/v1/map/droppod

¶

Spawns a drop pod at a specified position with given contents.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/map/droppod' \
--header 'content-type: application/json' \
--data '{
    "map_id": 0,
    "position": {"x": 15, "y": 0, "z": 15},
    "items": [{"def_name": "ComponentIndustrial", "quality": 3, "count": 1}],
    "open_delay": true
}'

Request:

{
    "map_id": 0,
    "position": {"x": 15, "y": 0, "z": 15},
    "items": [{"def_name": "ComponentIndustrial", "quality": 3, "count": 1}],
    "open_delay": true
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-31T11:04:27.9729153Z"
}

POST


/api/v1/map/zone/stockpile

¶

Create a new stockpile zone on the map with specific coordinate bounds and item filters.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/map/zone/stockpile' \
--header 'content-type: application/json' \
--data '{
    "map_id": 0,
    "point_a": {"x": 10, "y": 0, "z": 10},
    "point_b": {"x": 15, "y": 0, "z": 15},
    "name": "High Quality Steel",
    "priority": 4,
    "allowed_item_defs": ["Steel"],
    "allowed_item_categories": [],
    "min_hit_points_percent": 0.5,
    "max_hit_points_percent": 1.0,
    "min_quality": "Normal",
    "max_quality": "Legendary"
}'

Request:

{
    "map_id": 0,
    "point_a": {"x": 10, "y": 0, "z": 10},
    "point_b": {"x": 15, "y": 0, "z": 15},
    "name": "High Quality Steel",
    "priority": 4,
    "allowed_item_defs": ["Steel"],
    "allowed_item_categories": [],
    "min_hit_points_percent": 0.5,
    "max_hit_points_percent": 1.0,
    "min_quality": "Normal",
    "max_quality": "Legendary"
}

Response:

{
  "success": true,
  "data": {
    "zone_id": 6,
    "name": "Stockpile 3",
    "cells_count": 36,
    "priority": 0,
    "success": true,
    "message": "Stockpile 'Stockpile 3' created successfully with 36 cells."
  },
  "errors": [],
  "warnings": [],
  "timestamp": "2026-03-28T13:52:52.7387655Z"
}

POST


/api/v1/map/zone/stockpile/update

¶

Update an existing stockpile zone's parameters, including allowed items, categories, and quality/HP filters.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/map/zone/stockpile/update' \
--header 'content-type: application/json' \
--data '{
    "zone_id": 142,
    "name": "Updated Steel & Wood",
    "priority": 5,
    "add_item_defs": ["WoodLog"],
    "remove_item_defs": [],
    "add_item_categories": [],
    "remove_item_categories": [],
    "min_hit_points_percent": 0.1,
    "max_hit_points_percent": 1.0,
    "min_quality": "Awful",
    "max_quality": "Legendary"
}'

Request:

{
    "zone_id": 142,
    "name": "Updated Steel & Wood",
    "priority": 5,
    "add_item_defs": ["WoodLog"],
    "remove_item_defs": [],
    "add_item_categories": [],
    "remove_item_categories": [],
    "min_hit_points_percent": 0.1,
    "max_hit_points_percent": 1.0,
    "min_quality": "Awful",
    "max_quality": "Legendary"
}

Response:

{
    "success": true,
    "data": {
        "zone_id": 142,
        "name": "Updated Steel & Wood",
        "cells_count": 36,
        "priority": 5,
        "success": true,
        "message": null
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2026-03-28T14:35:00.0000000Z"
}

DELETE


/api/v1/map/zone/stockpile/delete

¶

Delete a stockpile zone by its zone ID.

Example:

curl --request DELETE \
--url 'http://localhost:8765/api/v1/map/zone/stockpile/delete?zone_id=142'

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2026-03-28T14:40:00.0000000Z"
}

POST


/api/v1/map/building/power

¶

Toggle the power state on or off for a flickable building (e.g., sun lamps, turrets, production benches) via its CompFlickable component.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/map/building/power?buildingId=123&powerOn=true'

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2026-03-28T16:00:00.0000000Z"
}

GET


/api/v1/datetime

¶

Retrieves the current in-game date and time according to the RimWorld world calendar.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/datetime

Response:

{
    "success": true,
    "data": {
        "datetime": "12th of Aprimay, 5500, 17h"
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:05:35.3244951Z"
}

GET


/api/v1/datetime/tile

¶

Retrieves the in-game date and time adjusted for a specific world tile's season offset.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/datetime/tile?tile=42'

Response:

{
    "success": true,
    "data": {
        "datetime": "12th of Aprimay, 5500, 17h"
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:05:35.3244951Z"
}

Global Map Controller¶

Operates on the Planetary scale. This controller interacts with objects that exist on the world map rather than the local colony map.

Caravans: Track movement, ETA, and inventory of traveling groups.
Settlements: locate other faction bases and quest sites.
Tiles: Query biome, temperature, and terrain data for specific world hexes.

GET


/api/v1/world/caravans

¶

Retrieves a list of all active caravans currently on the world map. This includes the player's caravans and visible non-player caravans. Returns details about location, destination, and contents (pawns/items).

Example:

curl --request GET \
--url http://localhost:8765/api/v1/world/caravans

Response:

{
    "success": true,
    "data": [
        {
        "id": 11,
        "name": "Rosa's caravan",
        "is_player_controlled": true,
        "position": {
            "x": 1,
            "y": 65,
            "z": -75
        },
        "tile": 232,
        "pawns": [
            {
            "id": 74,
            "name": "Rosa"
            }
        ],
        "items": [
            {
            "thing_id": 74,
            "def_name": "Human",
            "label": "Rosa<color=#999999FF>, Explorer</color>",
            "categories": [],
            "position": {
                "x": 143,
                "y": 0,
                "z": 62
            },
            "stack_count": 1,
            "market_value": 840.0,
            "is_forbidden": false,
            "quality": -1,
            "hit_points": 0,
            "max_hit_points": 0
            }
        ],
        "mass_usage": 0.75,
        "mass_capacity": 28.0,
        "forageability": "Forageable",
        "visibility": "0.16"
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-13T11:01:59.5952054Z"
}

GET


/api/v1/world/settlements

¶

Retrieves a list of all permanent settlements (bases) on the world map. This includes the player's colonies and other faction bases. Useful for finding trade partners or raid targets.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/world/settlements

Response:

{
    "success": true,
    "data": [
        {
            "id": 0,
            "name": "Planeton",
            "tile": 2241,
            "faction": {
                "load_id": 0,
                "def_name": "OutlanderCivil",
                "name": "Dinium",
                "is_player": false,
                "leader_title": "Spiritual Bodhisattva",
                "leader_id": 10
            }
        },
        {
            "id": 1,
            "name": "Borne",
            "tile": 1031,
            "faction": {
                "load_id": 1,
                "def_name": "TribeCivil",
                "name": "Union of Cheñoalo",
                "is_player": false,
                "leader_title": "Anima Chief",
                "leader_id": 19
            }
        },
        {
            "id": 2,
            "name": "Carsium",
            "tile": 387,
            "faction": {
                "load_id": 2,
                "def_name": "Empire",
                "name": "Imperium of God",
                "is_player": false,
                "leader_title": "High Stellarch",
                "leader_id": 25
            }
        },
            {
            "id": 3,
            "name": "Colony",
            "tile": 232,
            "faction": {
                "load_id": 14,
                "def_name": "PlayerColony",
                "name": "New Arrivals",
                "is_player": true,
                "leader_title": "Spirit Curate",
                "leader_id": 0
            }
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-13T11:02:36.2212158Z"
}

GET


/api/v1/world/sites

¶

Retrieves a list of temporary world sites. This includes quest locations, bandit camps, item stashes, ambushes, and other event-generated locations.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/world/sites

Response:

{
    "success": true,
    "data": [
        {
            "id": 12,
            "name": "outpost",
            "tile": 712,
            "faction": {
                "load_id": 7,
                "def_name": "PirateWaster",
                "name": "Gas Crew",
                "is_player": false,
                "leader_title": "Moral Thug",
                "leader_id": 59
            }
        },
        {
            "id": 13,
            "name": "bandit camp",
            "tile": 2720,
            "faction": {
                "load_id": 7,
                "def_name": "PirateWaster",
                "name": "Gas Crew",
                "is_player": false,
                "leader_title": "Moral Thug",
                "leader_id": 59
            }
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-13T11:04:31.8428299Z"
}

GET


/api/v1/world/tile

¶

Retrieves detailed ecological and geographical information about a specific world hex (tile) based on its ID. Returns biome, temperature, elevation, and road/river data.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/world/tile?id=12345"

Response:

{
    "success": true,
    "data": {
        "id": 232,
        "biome": "Tundra",
        "elevation": 1592.0,
        "temperature": -4.1,
        "rainfall": 269.0,
        "hilliness": "SmallHills",
        "roads": [
            "DirtRoad",
            "DirtRoad"
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-13T11:05:29.488063Z"
}

GET


/api/v1/world/caravan/path

¶

Retrieves the current movement status and planned path for a specific world caravan.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/world/caravan/path?caravan_id=12"

Response:

{
    "success": true,
    "data": {
        "id": 12,
        "moving": true,
        "current_tile": 150,
        "next_tile": 151,
        "progress": 0.45,
        "destination_tile": 180,
        "path": [
            151,
            152,
            160,
            180
        ]
    },
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

GET


/api/v1/world/player/settlements

¶

Retrieves a list of all settlements belonging to the player's faction.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/world/player/settlements

Response:

{
    "success": true,
    "data": [
        {
            "id": 123,
            "name": "Player's Hope",
            "tile": 5678,
            "faction": {
                "load_id": 3,
                "def_name": "PlayerColony",
                "name": "New Arrivals",
                "is_player": true
            }
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2026-01-04T12:00:00.000Z"
}

GET


/api/v1/world/grid/area

¶

Retrieves a list of world tiles within a specified radius of a center tile.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/world/grid/area?tile_id=12345&radius=5'

Response:

{
    "success": true,
    "data": [
        {
            "id": 12345,
            "biome": "Tundra",
            "elevation": 100.0,
            "temperature": -10.0,
            "rainfall": 200.0,
            "hilliness": "SmallHills",
            "roads": [],
            "rivers": [],
            "lat": 60.0,
            "lon": -30.0,
            "is_polluted": false,
            "pollution": 0.0
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2026-01-04T12:00:00.000Z"
}

GET


/api/v1/world/tile/coordinates

¶

Retrieves the latitude and longitude for a specific tile ID.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/world/tile/coordinates?id=12345'

Response:

{
    "success": true,
    "data": {
        "lat": 60.0,
        "lon": -30.0
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2026-01-04T12:00:00.000Z"
}

GET


/api/v1/world/tile/details

¶

Retrieves detailed information about a specific tile.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/world/tile/details?id=12345'

Response:

{
    "success": true,
    "data": {
        "id": 12345,
        "biome": "Tundra",
        "elevation": 100.0,
        "temperature": -10.0,
        "rainfall": 200.0,
        "hilliness": "SmallHills",
        "roads": [
            "279644:StoneRoad",
            "279641:StoneRoad"
        ],
        "rivers": [
            "279640:Creek",
            "279686:Creek"
        ],
        "lat": 60.0,
        "lon": -30.0,
        "is_polluted": false,
        "pollution": 0.0,
        "time_zone": "2",
        "forageability": 0.5,
        "growing_period": "Year-round",
        "movement_difficulty": 1.0,
        "stone_types": [
            "Sandstone",
            "Granite"
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2026-01-04T12:00:00.000Z"
}

GET


/api/v1/world/grid

¶

Retrieves the entire world grid, returning a list of all tiles with their basic information.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/world/grid

Response:

{
    "success": true,
    "data": [
        {
            "id": 0,
            "biome": "Ocean",
            "elevation": -100.0,
            "temperature": 10.0,
            "rainfall": 500.0,
            "hilliness": "Flat",
            "roads": [
                "279644:StoneRoad",
                "279641:StoneRoad"
            ],
            "rivers": [
                "279640:Creek",
                "279686:Creek"
            ],
            "lat": -90.0,
            "lon": 0.0,
            "is_polluted": false,
            "pollution": 0.0
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2026-01-04T12:00:00.000Z"
}

Builder Controller¶

The Builder Controller provides tools for programmatic construction and deconstruction. It allows for copying, pasting, and blueprinting areas of the map.

POST


/api/v1/builder/copy

¶

Copies a specified area of the map, including buildings, items, and terrain. The copied data can be used with the paste endpoint.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/builder/copy \
--header 'content-type: application/json' \
--data '{
    "from": { "x": 100, "z": 100 },
    "to": { "x": 110, "z": 110 }
}'

Response:

{
    "map_id": 0,
    "point_a": {"x": 10, "y": 0, "z": 10},
    "point_b": {"x": 16, "y": 0, "z": 16}
}

Response:

{
    "success":true,
    "data": {
        "width":7,
        "height":7,
        "floors": [
            {"def_name":"Concrete","rel_x":1,"rel_z":1},
            {"def_name":"Concrete","rel_x":3,"rel_z":2}],
        "buildings": [
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":0,"rel_z":0,"rotation":0},
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":3,"rel_z":0,"rotation":0},
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":0,"rel_z":1,"rotation":0},
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:15:20.9851409Z"
}

POST


/api/v1/builder/paste

¶

Pastes a previously copied area to a new location on the map.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/builder/paste \
--header 'content-type: application/json' \
--data '{
    "at": { "x": 150, "z": 150 }
}'

Request:

{
    "map_id": 0,
    "position": {"x": 80, "y": 0, "z": 80},
    "blueprint": {
        "width":7,
        "height":7,
        "floors": [
            {"def_name":"Concrete","rel_x":1,"rel_z":1},
            {"def_name":"Concrete","rel_x":3,"rel_z":2}],
        "buildings": [
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":0,"rel_z":0,"rotation":0},
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":3,"rel_z":0,"rotation":0},
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":0,"rel_z":1,"rotation":0},
        ]
    },
    "clear_obstacles": true,
}

Response:

{
    "success":true,
    "errors":[],
    "warnings":[],
    "timestamp":"2025-12-31T12:18:40.2019606Z"
}

POST


/api/v1/builder/check-zone

¶

Validates whether a zone can be created at the given set of cells without committing to the creation. Returns which cells are free, which are already occupied by another zone, and which are out of map bounds.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/builder/check-zone \
--header 'content-type: application/json' \
--data '{
    "map_id": 0,
    "point_a": {"x": 50, "y": 0, "z": 50},
    "point_b": {"x": 55, "y": 0, "z": 55}
}'

Request:

{
    "map_id": 0,
    "point_a": {"x": 50, "y": 0, "z": 50},
    "point_b": {"x": 55, "y": 0, "z": 55}
}

Response:

{
    "success": true,
    "data": {
        "free_cells": 30,
        "occupied_cells": 6,
        "out_of_bounds_cells": 0,
        "can_create": true
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-31T12:18:40.2019606Z"
}

POST


/api/v1/builder/blueprint

¶

Places blueprints for a copied area, allowing colonists to construct the buildings.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/builder/blueprint \
--header 'content-type: application/json' \
--data '{
    "at": { "x": 150, "z": 150 }
}'

Request:

{
    "map_id": 0,
    "position": {"x": 80, "y": 0, "z": 80},
    "blueprint": {
        "width":7,
        "height":7,
        "floors": [
            {"def_name":"Concrete","rel_x":1,"rel_z":1},
            {"def_name":"Concrete","rel_x":3,"rel_z":2}],
        "buildings": [
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":0,"rel_z":0,"rotation":0},
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":3,"rel_z":0,"rotation":0},
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":0,"rel_z":1,"rotation":0},
        ]
    },
}

Response:

{
    "success":true,
    "errors":[],
    "warnings":[],
    "timestamp":"2025-12-31T12:18:40.2019606Z"
}

BillController¶

GET


/api/v1/map/work-tables

¶

Get a list of all work tables (buildings capable of holding bills) currently spawned on the map.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/map/work-tables?map_id=0'

Response:

{
    "success": true,
    "data": [
        {
            "id": 14502,
            "thing_def": "TableButcher",
            "label": "butcher table",
            "position": {"x": 120, "y": 0, "z": 95},
            "bills_count": 2
        }
    ]
}

GET


/api/v1/buildings/recipes

¶

Get a list of all available recipes that can be crafted at a specific work table.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/buildings/recipes?building_id=14502'

Response:

{
    "success": true,
    "data": [
        {
            "def_name": "Make_MeleeWeapon_Club",
            "label": "make club",
            "description": "Craft a simple club.",
            "work_amount": 3000.0,
            "work_skill": "Crafting"
        }
    ]
}

GET


/api/v1/buildings/bills

¶

List all active and suspended bills currently queued on a specific work table.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/buildings/bills?building_id=14502'

Response:

{
    "success": true,
    "data": [
        {
            "load_id": 402,
            "recipe_def_name": "Make_MeleeWeapon_Club",
            "repeat_mode": "RepeatCount",
            "repeat_count": 5
        }
    ]
}

POST


/api/v1/buildings/bills/add

¶

Create a new bill and add it to the work table's queue.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/buildings/bills?building_id=14502' \
--header 'content-type: application/json' \
--data '{
    "recipe_def_name": "Make_MeleeWeapon_Club",
    "repeat_mode": "RepeatCount",
    "repeat_count": 5
}'

Request:

{
    "recipe_def_name": "Make_MeleeWeapon_Club",
    "repeat_mode": "RepeatCount",
    "repeat_count": 5
}

Response:

{
    "success": true,
    "data": {
        "load_id": 403,
        "recipe_def_name": "Make_MeleeWeapon_Club"
    }
}

DELETE


/api/v1/buildings/bills/remove

¶

Completely clear and delete all bills from a specific work table.

Example:

curl --request DELETE \
--url 'http://localhost:8765/api/v1/buildings/bills?building_id=14502'

Response:

{
    "success": true,
    "data": null
}

GET


/api/v1/buildings/bill

¶

Get detailed configuration properties of a single specific bill.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/buildings/bill?building_id=14502&bill_id=402'

Response:

{
    "success": true,
    "data": {
        "load_id": 402,
        "recipe_def_name": "Make_MeleeWeapon_Club",
        "suspended": false
    }
}

PUT


/api/v1/buildings/bill/update

¶

Update the configuration properties (like target count or allowed materials) of an existing bill.

Example:

curl --request PUT \
--url 'http://localhost:8765/api/v1/buildings/bill?building_id=14502&bill_id=402' \
--header 'content-type: application/json' \
--data '{
    "repeat_mode": "TargetCount",
    "target_count": 10
}'

Request:

{
    "repeat_mode": "TargetCount",
    "target_count": 10
}

Response:

{
    "success": true,
    "data": {
        "load_id": 402,
        "repeat_mode": "TargetCount",
        "target_count": 10
    }
}

DELETE


/api/v1/buildings/bill/remove

¶

Delete a single bill from the work table.

Example:

curl --request DELETE \
--url 'http://localhost:8765/api/v1/buildings/bill?building_id=14502&bill_id=402'

Response:

{
    "success": true,
    "data": null
}

PUT


/api/v1/buildings/bill/reorder

¶

Shift a bill up or down in the work table's queue. A negative offset moves the bill up (higher priority), a positive offset moves it down.

Example:

curl --request PUT \
--url 'http://localhost:8765/api/v1/buildings/bill/reorder?building_id=14502&bill_id=402' \
--header 'content-type: application/json' \
--data '{"offset": -1}'

Request:

{
    "offset": -1
}

Response:

{
    "success": true,
    "data": null
}

PUT


/api/v1/buildings/bill/suspend

¶

Suspend (pause) or resume an existing bill.

Example:

curl --request PUT \
--url 'http://localhost:8765/api/v1/buildings/bill/suspend?building_id=14502&bill_id=402' \
--header 'content-type: application/json' \
--data '{"suspended": true}'

Request:

{
    "suspended": true
}

Response:

{
    "success": true,
    "data": null
}

🌍 Map & Environment API¶

Map Controller¶

GET /api/v1/map/things ¶

GET /api/v1/maps ¶

GET /api/v1/map/pawns ¶

GET /api/v1/map/terrain ¶

GET /api/v1/map/things-at ¶

GET /api/v1/map/things/radius ¶

GET /api/v1/map/ore ¶

GET /api/v1/map/fog-grid ¶

GET /api/v1/map/plants ¶

GET /api/v1/map/weather ¶

GET /api/v1/map/animals ¶

GET /api/v1/map/zones ¶

GET /api/v1/map/building/info ¶

POST /api/v1/map/weather/change ¶

GET /api/v1/map/power/info ¶

GET /api/v1/map/creatures/summary ¶

GET /api/v1/map/farm/summary ¶

POST /api/v1/map/zone/growing ¶

GET /api/v1/map/rooms ¶

GET /api/v1/map/buildings ¶

POST /api/v1/map/destroy/corpses ¶

POST /api/v1/map/destroy/forbidden ¶

POST /api/v1/map/destroy/rect ¶

POST /api/v1/map/repair/positions ¶

POST /api/v1/map/repair/rect ¶

POST /api/v1/map/droppod ¶

POST /api/v1/map/zone/stockpile ¶

POST /api/v1/map/zone/stockpile/update ¶

DELETE /api/v1/map/zone/stockpile/delete ¶

POST /api/v1/map/building/power ¶

GET /api/v1/datetime ¶

GET /api/v1/datetime/tile ¶

Global Map Controller¶

GET /api/v1/world/caravans ¶

GET /api/v1/world/settlements ¶

GET /api/v1/world/sites ¶

GET /api/v1/world/tile ¶

GET /api/v1/world/caravan/path ¶

GET /api/v1/world/player/settlements ¶

GET /api/v1/world/grid/area ¶

GET /api/v1/world/tile/coordinates ¶

GET /api/v1/world/tile/details ¶

GET /api/v1/world/grid ¶

Builder Controller¶

POST /api/v1/builder/copy ¶

POST /api/v1/builder/paste ¶

POST /api/v1/builder/check-zone ¶

POST /api/v1/builder/blueprint ¶

BillController¶

GET /api/v1/map/work-tables ¶

GET /api/v1/buildings/recipes ¶

GET /api/v1/buildings/bills ¶

POST /api/v1/buildings/bills/add ¶

DELETE /api/v1/buildings/bills/remove ¶

GET /api/v1/buildings/bill ¶

PUT /api/v1/buildings/bill/update ¶

DELETE /api/v1/buildings/bill/remove ¶

PUT /api/v1/buildings/bill/reorder ¶

PUT /api/v1/buildings/bill/suspend ¶

GET

`/api/v1/map/things` ¶

GET

`/api/v1/maps` ¶

GET

`/api/v1/map/pawns` ¶

GET

`/api/v1/map/terrain` ¶

GET

`/api/v1/map/things-at` ¶

GET

`/api/v1/map/things/radius` ¶

GET

`/api/v1/map/ore` ¶

GET

`/api/v1/map/fog-grid` ¶

GET

`/api/v1/map/plants` ¶

GET

`/api/v1/map/weather` ¶

GET

`/api/v1/map/animals` ¶

GET

`/api/v1/map/zones` ¶

GET

`/api/v1/map/building/info` ¶

POST

`/api/v1/map/weather/change` ¶

GET

`/api/v1/map/power/info` ¶

GET

`/api/v1/map/creatures/summary` ¶

GET

`/api/v1/map/farm/summary` ¶

POST

`/api/v1/map/zone/growing` ¶

GET

`/api/v1/map/rooms` ¶

GET

`/api/v1/map/buildings` ¶

POST

`/api/v1/map/destroy/corpses` ¶

POST

`/api/v1/map/destroy/forbidden` ¶

POST

`/api/v1/map/destroy/rect` ¶

POST

`/api/v1/map/repair/positions` ¶

POST

`/api/v1/map/repair/rect` ¶

POST

`/api/v1/map/droppod` ¶

POST

`/api/v1/map/zone/stockpile` ¶

POST

`/api/v1/map/zone/stockpile/update` ¶

DELETE

`/api/v1/map/zone/stockpile/delete` ¶

POST

`/api/v1/map/building/power` ¶

GET

`/api/v1/datetime` ¶

GET

`/api/v1/datetime/tile` ¶

GET

`/api/v1/world/caravans` ¶

GET

`/api/v1/world/settlements` ¶

GET

`/api/v1/world/sites` ¶

GET

`/api/v1/world/tile` ¶

GET

`/api/v1/world/caravan/path` ¶

GET

`/api/v1/world/player/settlements` ¶

GET

`/api/v1/world/grid/area` ¶

GET

`/api/v1/world/tile/coordinates` ¶

GET

`/api/v1/world/tile/details` ¶

GET

`/api/v1/world/grid` ¶

POST

`/api/v1/builder/copy` ¶

POST

`/api/v1/builder/paste` ¶

POST

`/api/v1/builder/check-zone` ¶

POST

`/api/v1/builder/blueprint` ¶

GET

`/api/v1/map/work-tables` ¶

GET

`/api/v1/buildings/recipes` ¶

GET

`/api/v1/buildings/bills` ¶

POST

`/api/v1/buildings/bills/add` ¶

DELETE

`/api/v1/buildings/bills/remove` ¶

GET

`/api/v1/buildings/bill` ¶

PUT

`/api/v1/buildings/bill/update` ¶

DELETE

`/api/v1/buildings/bill/remove` ¶

PUT

`/api/v1/buildings/bill/reorder` ¶

PUT

`/api/v1/buildings/bill/suspend` ¶