⚙️ Game State & Mechanics API¶

This section handles the core game lifecycle (save/load/pause), triggering random events, managing factions, and research.

Game Controller¶

This controller handles the general game functions.

GET


/api/v1/game/state

¶

Disable server caching for endpoint results.

Example:

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

Response:

{
    "success": true,
    "data": {
        "game_tick": 120,
        "colony_wealth": 4.0,
        "colonist_count": 3,
        "storyteller": "Cassandra",
        "is_paused": true
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:39:28.6476222Z"
}

POST


/api/v1/game/speed

¶

Sets the current game time speed.

Info

Speed Values:

`0`: Paused
`1`: Normal Speed
`2`: Fast Speed
`3`: Super Fast Speed
`4`: Ultra Fast (Dev Mode only)

Example:

curl --request POST \
--url "http://localhost:8765/api/v1/game/speed?speed=3"

Response:

{
    "success": true,
    "data": "Game speed set to 3",
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-14T14:10:05.123Z"
}

GET


/api/v1/game/settings/run-in-background

¶

Retrieves the current state of the "Run in Background" setting.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/game/settings/run-in-background

Response:

{
    "success": true,
    "data": true,
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

POST


/api/v1/game/settings/toggle/run-in-background

¶

Toggles or sets the "Run in Background" setting. The request body determines the desired state.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/game/settings/toggle/run-in-background \
--header 'Content-Type: application/json' \
--data 'true'

Response:

{
    "success": true,
    "data": true,
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

GET


/api/v1/version

¶

Retrieves version information for the game, the REST API mod, and the API itself. This endpoint provides essential identification metadata that can be used for compatibility checks, debugging, and system documentation.

Example:

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

Response:

{
    "success": true,
    "data": {
        "rim_world_version": "1.5.4243",
        "mod_version": "1.2.0",
        "api_version": "v1"
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T18:52:09.0916968Z"
}

GET


/api/v1/mods/list

¶

Returns a list of all currently active mods with their metadata.

Example:

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

Response:

{
    "success": true,
    "data": [
        {
            "name": "Core",
            "package_id": "ludeon.rimworld",
            "load_order": 0
        },
        {
            "name": "RIMAPI",
            "package_id": "redeyedev.rimapi",
            "load_order": 1
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T18:53:40.5041431Z"
}

GET


/api/v1/mods/info

¶

Returns information about installed mods. Can be filtered by package_id to get detailed info for a single mod.

Example (All mods):

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

Example (Single mod):

curl --request GET \
--url http://localhost:8765/api/v1/mods/info?package_id=RedEyeDev.RIMAPI

Response:

{
    "success": true,
    "data": [
        {
        "name": "RIMAPI",
        "package_id": "RedEyeDev.RIMAPI",
        "load_order": 3,
        "author": "RedEyeDev",
        "description": "RIMAPI is a mod...",
        "url": "https://...",
        "version": "1.9.0",
        "supported_versions": ["1.5", "1.6"],
        "root_dir": "..."
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "..."
}

GET


/api/v1/mods/preview

¶

Returns the mod's preview image as a base64 encoded string.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/mods/preview?package_id=RedEyeDev.RIMAPI

Response:

{
    "success": true,
    "data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "errors": [],
    "warnings": [],
    "timestamp": "..."
}

POST


/api/v1/mods/configure

¶

Configures the active mods list and their load order. Pass an array of package IDs in the exact order you want them loaded. Core (ludeon.rimworld) will be automatically prepended if missing. Set restart_game to true to immediately reboot RimWorld and apply the changes.

Example:

curl --request POST \
  --url http://localhost:8765/api/v1/mods/configure \
  --header 'content-type: application/json' \
  --data '{"package_ids":["brrainz.harmony","ludeon.rimworld","ludeon.rimworld.royalty","ludeon.rimworld.ideology","ludeon.rimworld.biotech","ludeon.rimworld.anomaly","ludeon.rimworld.odyssey","unlimitedhugs.hugslib","redeyedev.rimapi"],"restart_game":true}'

Request Body:

{
  "package_ids": [
    "brrainz.harmony",
    "ludeon.rimworld",
    "ludeon.rimworld.royalty",
    "ludeon.rimworld.ideology",
    "ludeon.rimworld.biotech",
    "ludeon.rimworld.anomaly",
    "ludeon.rimworld.odyssey",
    "unlimitedhugs.hugslib",
    "redeyedev.rimapi"
  ],
  "restart_game": true
}

Response:

{
    "success": true,
    "data": null,
    "errors": [],
    "warnings": [],
    "timestamp": "2026-02-18T18:23:32.0000000Z"
}

POST


/api/v1/select

¶

Selects a specific in-game object (pawn, building, item, etc.) based on its type and unique identifier.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/select?type=pawn&id=443'

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

POST


/api/v1/deselect

¶

Clears the current in-game selection, removing any highlighted objects and returning the interface to a neutral state.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/deselect

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

POST


/api/v1/open-tab

¶

Opens a specific information panel (tab) for the currently selected pawn in the game's inspection pane. This endpoint allows external control to view detailed information about a pawn's health, equipment, needs, relationships, and other attributes—mirroring the tab interface available when manually inspecting a character in-game.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/open-tab?name=health'

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

GET


/api/v1/def/all

¶

Retrieves comprehensive information about all game definition entries (defs) from RimWorld's data system. Definitions are the core data structures that define nearly every element in the game, including items, buildings, creatures, terrain, research projects, and more.

Info

Things Defs

Example

{
    "def_name": "Beer",
    "label": "beer",
    "description": "The first beverage besides water ever consumed by mankind. Beer can taste good, but its main effect is intoxication. Excessive consumption can lead to alcohol blackouts and, over time, addiction.",
    "category": "Item",
    "thing_class": "ThingWithComps",
    "stat_base": {
    "max_hit_points": 50.0,
    "flammability": 0.5,
    "deterioration_rate": 0.5,
    "beauty": -4.0,
    "market_value": 12.0,
    "mass": 0.3,
    "nutrition": 0.08
    },
    "is_weapon": true,
    "is_apparel": false,
    "is_item": true,
    "is_pawn": false,
    "is_plant": false,
    "is_building": false,
    "is_medicine": false,
    "is_drug": true,
    "market_value": 12.0,
    "mass": 0.3,
    "max_hit_points": 50.0,
    "flammability": 0.5,
    "stack_limit": 25,
    "nutrition": 0.08,
    "work_to_make": 1.0,
    "work_to_build": 1.0,
    "beauty": -4.0,
    "max_health": 0.0,
    "armor_rating__sharp": 0.0,
    "armor_rating__blunt": 0.0,
    "armor_rating__heat": 0.0,
    "insulation__cold": 0.0,
    "insulation__heat": 0.0
}

Incidents Defs

Example

{
    "def_name": "BloodRain",
    "label": "Blood rain",
    "base_chance": 0.5,
    "base_chance_with_royalty": -1.0,
    "letter_def_name": "ThreatBig",
    "population_effect": "0",
    "min_population": 0,
    "min_threat_points": -3.40282347E+38,
    "max_threat_points": 3.40282347E+38,
    "category": "ThreatBig",
    "should_ignore_recent_weighting": false,
    "tags": [],
    "disallowed_biomes": [],
    "allowed_biomes": [],
    "require_colonists_present": false
},

Conditions Defs
PawnKind Defs
Trait Defs
Research Defs
Hediff Defs

Example

{
    "def_name": "GoJuiceHigh",
    "label": "High on go-juice",
    "description": "Go-juice in the bloodstream. It supercharges combat-related abilities, and instantly increases psyfocus when first injected.",
    "hediff_class": "Hediff_High",
    "is_addiction": false,
    "makes_sick_thought": false,
    "severity_per_day": 0.0,
    "max_severity": 1.0,
    "tendable": false,
    "is_bad": false,
    "stages": [
    {
        "min_severity": 0.0,
        "death_mtb_days": -1.0,
        "pain_factor": 0.1,
        "forget_memory_thought_mtb_days": -1.0,
        "vomit_mtb_days": -1.0,
        "mental_break_mtb_days": -1.0
    }
    ]
}

Skill Defs
WorkType Defs
Need Defs
Thought Defs
Stat Defs
WorldObject Defs
Biome Defs
Terrain Defs
Recipe Defs
Body Defs
BodyPart Defs
Faction Defs
Sound Defs
DesignationCategory Defs
JoyKind Defs
Meme Defs
Precept Defs
Ability Defs
Gene Defs
Weather Defs
RoomRole Defs
RoomStat Defs
MentalState Defs
DrugPolicy Defs
Plant Defs
Animal Defs
Storyteller Defs

Example

{
    "def_name": "Cassandra"
},
{
    "def_name": "Phoebe"
},
{
    "def_name": "Randy"
},
{
    "def_name": "Tutor"
}

Difficulty Defs

Example

{
    "def_name": "Peaceful"
},
{
    "def_name": "Easy"
},
{
    "def_name": "Medium"
},
{
    "def_name": "Rough"
},
{
    "def_name": "Hard"
},
{
    "def_name": "Extreme"
},
{
    "def_name": "Custom"
}

Example:

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

Response:

{
    "success": true,
    "data": {
        "things_defs": [
            {
                "def_name": "TextBook",
                "label": "textbook",
                "description": "A book which focuses on teaching skills.",
                "category": "Item",
                "thing_class": "Book",
                "stat_base": {
                "max_hit_points": 60.0,
                "deterioration_rate": 5.0,
                "mass": 0.5,
                "flammability": 1.0,
                "beauty": 1.0,
                "market_value": 160.0
                },
                "is_weapon": false,
                "is_apparel": false,
                "is_item": true,
                "is_pawn": false,
                "is_plant": false,
                "is_building": false,
                "is_medicine": false,
                "is_drug": false,
                "market_value": 160.0,
                "mass": 0.5,
                "max_hit_points": 60.0,
                "flammability": 1.0,
                "stack_limit": 1,
                "nutrition": 0.0,
                "work_to_make": 1.0,
                "work_to_build": 1.0,
                "beauty": 1.0,
                "max_health": 0.0,
                "armor_rating__sharp": 0.0,
                "armor_rating__blunt": 0.0,
                "armor_rating__heat": 0.0,
                "insulation__cold": 0.0,
                "insulation__heat": 0.0
            },
            {
                <...>
            }
        ],
        "incidents_defs": [],
        "conditions_defs": [],
        "pawn_kind_defs": [],
        "trait_defs": [],
        "research_defs": [],
        "hediff_defs": [],
        "skill_defs": [],
        "work_type_defs": [],
        "need_defs": [],
        "stat_defs": [],
        "world_object_defs": [],
        "biome_defs": [],
        "terrain_defs": [],
        "recipe_defs": [],
        "body_defs": [],
        "body_part_defs": [],
        "faction_defs": [],
        "sound_defs": [],
        "designation_category_defs": [],
        "joy_kind_defs": [],
        "meme_defs": [],
        "precept_defs": [],
        "ability_defs": [],
        "gene_defs": [],
        "weather_defs": [],
        "room_role_defs": [],
        "room_stat_defs": [],
        "mental_state_defs": [],
        "drug_policy_defs": [],
        "plant_defs": [],
        "animal_defs": [],
        "job_defs": []
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:09:46.047553Z"
}

POST


/api/v1/game/select-area

¶

Simulates a drag-select action in the game world (UI). Selects all selectable objects (colonists, items, etc.) within the rectangle defined by PositionA and PositionB.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/game/select-area \
--header 'Content-Type: application/json' \
--data '{
    "position_a": { "x": 10, "y": 0, "z": 10 },
    "position_b": { "x": 20, "y": 0, "z": 20 }
}'

Request Body:

{
    "position_a": { "x": 10, "y": 0, "z": 10 },
    "position_b": { "x": 20, "y": 0, "z": 20 }
}

Response:

{
    "success": true,
    "data": "Area selected from (10, 0, 10) to (20, 0, 20). 5 objects selected.",
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-14T14:18:10.000Z"
}

POST


/api/v1/game/send/letter

¶

Manually triggers an in-game notification letter (message) with custom title, text, and type (e.g., neutral, negative, positive, threat).

Example:

curl --request POST \
--url http://localhost:8765/api/v1/game/send/letter

Request:

{
    "label": "New Message Label",
    "message": "Hello RimWorld!",
    "letter_def": "NeutralEvent"
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

POST


/api/v1/game/save

¶

Saves the current game state to a file with the specified name.

Example:

curl --request POST \
--url "http://localhost:8765/api/v1/game/save?name=MyApiSave"

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-20T10:00:00.000Z"
}

POST


/api/v1/game/load

¶

Try to loads a game state from a save file with the specified name.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/game/load?name=MyApiSave"

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-20T10:01:00.000Z"
}

POST


/api/v1/game/start/devquick

¶

Starts a new game immediately using the developer 'quick start' configuration, bypassing character selection and landing site choice. This is useful for rapid testing.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/game/start/devquick

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-20T10:02:00.000Z"
}

POST


/api/v1/game/start

¶

This endpoint starts a new RimWorld game with the specified configuration parameters. It initializes a new game world with the given storyteller, difficulty, map settings, and planet generation parameters.

Getting Available Options

Storyteller names, difficulty levels, and other definition values can be retrieved from the /api/v1/def/all endpoint. This endpoint provides comprehensive information about all game definitions, including:

Storyteller definitions
Difficulty settings

Example usage:

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

The response is a large json structure from the game, it contains categorized definitions that can be used to populate the parameters for this game start request.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/game/start \
--header 'Content-Type: application/json' \
--data '{
    "storyteller_name": "Randy",
    "difficulty_name": "Peaceful",
    "map_size": 120,
    "permadeath": false,
    "planet_coverage": 0.1,
    "world_seed": "rickroll",
    "starting_tile": "7298",
    "starting_season": "2",
    "overall_rainfall": 2,
    "overall_temperature": 2,
    "overall_population": 2,
    "landmark_density": 2
}'

Request:

{
    "storyteller_name": "Randy",
    "difficulty_name": "Peaceful",
    "map_size": 120,
    "permadeath": false,
    "planet_coverage": 0.1,
    "world_seed": "rickroll",
    "starting_tile": "7298",
    "starting_season": "2",
    "overall_rainfall": 2,
    "overall_temperature": 2,
    "overall_population": 2,
    "landmark_density": 2
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-20T10:03:00.000Z"
}

GET


/api/v1/game/settings

¶

Retrieves the current game configuration settings. This endpoint provides access to various gameplay, audio, video, and interface preferences.

Example:

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

Response:

{
    "success": true,
    "data": {
        "language": "English",
        "run_in_background": true,
        "development_mode": true,
        "log_verbose": false,
        "temperature_mode": "Celsius",
        "autosave_interval": true,
        "resolution": "1024x768",
        "fullscreen": false,
        "user_interface_scale": 1.0,
        "custom_cursor_enabled": true,
        "hats_only_on_map": false,
        "plant_wind_sway": true,
        "max_number_of_player_settlements": 1,
        "volume_master": 0.6375921,
        "volume_game": 0.7051597,
        "volume_music": 0.0,
        "volume_ambient": 0.6007371,
        "pause_on_load": false,
        "pause_on_urgent_letter": "MajorThreat",
        "automatic_pause_on_letter": false,
        "edge_screen_scroll": true,
        "map_drag_sensitivity": 1.3,
        "zoom_to_mouse": false,
        "show_realtime_clock": true,
        "resource_readout_categorized": false,
        "show_animal_names": false,
        "reset_mods_config_on_crash": false,
        "texture_compression": 0
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-20T12:30:35.4174593Z"
}

POST


/api/v1/game/main-menu

¶

Return to the main menu from an active game session. Any unsaved progress will be lost.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/game/main-menu'

Response:

{
    "success": true,
    "data": "Returning to main menu...",
    "errors": [],
    "warnings": [],
    "timestamp": "2026-04-01T17:13:42.0000000Z"
}

POST


/api/v1/game/quit

¶

Completely shut down the RimWorld application and exit to the desktop.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/game/quit'

Response:

{
    "success": true,
    "data": "Shutting down the game...",
    "errors": [],
    "warnings": [],
    "timestamp": "2026-04-01T17:13:42.0000000Z"
}

Game Events Controller¶

The Game Events Controller allows external systems to act as the "Storyteller," forcing specific incidents to occur immediately.

Narrative Control

This is useful for Twitch integrations or scenario managers that want to trigger raids, weather changes, or drop pods on demand.

Supported Event Types:

Threats: Raids, Manhunters, Infestations.
Weather: Rain, Fog, Eclipses, Solar Flares.
Misc: Trader arrivals, Quest triggers.

GET


/api/v1/quests

¶

Retrieves a list of all active and historical quests.

Example:

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

Response:

{
    "success": true,
    "data": {
        "active_quests": [
        {
            "id": 1,
            "quest_def": "OpportunitySite_ItemStash",
            "name": "Choma's Shack of Valuables",
            "description": "<color=#D09B61FF>Choma</color>, Great Chief of <color=#00BFFFFF>Coalition of Tol</color>, has informed us of a collection of valuable items worth $535 not far from us. The collection consists of:\n\n  - The Archaic Psychoid Chronicle (excellent)\r\n  - Voro-Harbinger (good)\n\n<color=#D09B61FF>Choma</color> says that there may be an <color=#D46F68FF>unknown threat</color>.",
            "state": "Ongoing",
            "expiry_hours": -0.000400000019,
            "reward": [
            "Reward_Items(value $535)\n  -Voro-Harbinger (good) $310\n  -The Archaic Psychoid Chronicle (excellent) $225"
            ]
        }
        ],
        "historical_quests": [
        {
            "id": 0,
            "quest_def": "Beggars",
            "name": "Drifter Hopes for Resources",
            "description": "A poor traveler named <color=#D09B61FF>Ace</color> is approaching looking for help. <color=#D09B61FF>Ace</color> is begging for x700 silver. <color=#D09B61FF>Ace</color> wants the silver to pay off a debt to a gang of pirates who are hunting her.\n\nYou can give items to <color=#D09B61FF>Ace</color> by selecting a colonist and right-clicking on her.\n\n<color=#D09B61FF>Ace</color> will move on after <color=#87F6F6FF>1 day</color>.\n\nThis traveler is not part of any faction. If you wish, you can choose to kill, arrest, sell, or harvest her, without diplomatic consequences.",
            "state": "EndedSuccess",
            "expiry_hours": -0.000400000019,
            "reward": []
        }
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:43:32.2659508Z"
}

GET


/api/v1/incidents

¶

Description

Example:

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

Response:

{
    "success": true,
    "data": {
        "incidents": [
            {
                "incident_def": "VisitorGroup",
                "label": "visitor group",
                "category": "None",
                "incident_hour": 60.0,
                "days_since_occurred": 0.1068
            },
            {
                "incident_def": "GiveQuest_Beggars",
                "label": "beggars arrive",
                "category": "GiveQuest",
                "incident_hour": 8.8,
                "days_since_occurred": 2.24013329
            }
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:24:31.91622Z"
}

GET


/api/v1/lords

¶

Retrieves detailed information about all active "Lord" processes on a specified map. In RimWorld, a Lord represents a high-level AI manager that coordinates groups of pawns toward a common objective—such as raiding, visiting or trading.

Example:

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

Response:

{
    "success": true,
    "data": [
        {
            "load_id": 2,
            "faction_name": "Nation of Iralaguaro",
            "faction_def_name": "TribeCivil",
            "lord_job_type": "LordJob_VisitColony",
            "current_toil_name": "LordToil_DefendPoint",
            "ticks_in_toil": 2231,
            "num_pawns_lost_violently": 0,
            "num_pawns_ever_gained": 1,
            "owned_pawn_ids": [
                "Human8834"
            ],
            "owned_building_ids": [],
            "any_active_pawn": true
        },
        {
            "load_id": 3,
            "faction_name": "Cancer Unit",
            "faction_def_name": "PirateWaster",
            "lord_job_type": "LordJob_StageThenAttack",
            "current_toil_name": "LordToil_Stage",
            "ticks_in_toil": 0,
            "num_pawns_lost_violently": 0,
            "num_pawns_ever_gained": 1,
            "owned_pawn_ids": [
                "Human8861"
            ],
            "owned_building_ids": [],
            "any_active_pawn": true
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:26:22.0370532Z"
}

GET


/api/v1/incidents/top

¶

Returns a list of incidents with the highest current weight (probability) of occurring, based on the current Storyteller settings and game state. Accepts an optional limit parameter.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/incidents/top?limit=3"

Response:

{
    "success": true,
    "data": [
        {
            "def_name": "RaidEnemy",
            "label": "enemy raid",
            "category": "ThreatBig",
            "current_weight": 1.2
        },
        {
            "def_name": "TraderCaravan",
            "label": "trader caravan",
            "category": "Misc",
            "current_weight": 0.85
        },
        {
            "def_name": "TravelerGroup",
            "label": "travelers",
            "category": "Misc",
            "current_weight": 0.5
        }
    ],
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

GET


/api/v1/incident/chance

¶

Calculates the specific probability weight for a single incident definition.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/incident/chance?incident_def_name=RaidEnemy"

Request Body (or Query Params):

{
    "incident_def_name": "RaidEnemy"
}

Response:

{
    "success": true,
    "data": {
        "value": 1.2
    },
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

POST


/api/v1/incident/trigger

¶

Manually triggers a specific in-game incident (event) immediately.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/incident/trigger \
--header 'content-type: application/json' \
--data '{
    "name": "RaidEnemy",
    "map_id": "0",
    "incident_parms": {
        "points": 300.0,
        "forced": true,
        "faction": "Pirate",
        "send_letter": true,
        "custom_letter_label": "API Raid Test",
        "custom_letter_text": "Test raid triggered via API"
    }
}'

Request:

{
    "name": "RaidEnemy",
    "map_id": "0",
    "incident_parms": {
        "points": 300.0,
        "forced": true,
        "faction": "Pirate",
        "send_letter": true,
        "custom_letter_label": "API Raid Test",
        "custom_letter_text": "Test raid triggered via API"
    }
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

Faction Controller¶

The Faction Controller manages the geopolitical landscape of the world. It allows for the inspection and manipulation of relationships between the player's colony and other groups.

Key Functions:

Diplomacy: Adjust goodwill and relation status (Hostile/Neutral/Ally).
Registry: List all generated factions and their leaders.
Interaction: Trigger faction-specific requests or gifts.

GET


/api/v1/factions

¶

Retrieves a list of all factions currently known in the game world.

Example:

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

Response:

{
    "success": true,
    "data": [
        {
            "load_id": 0,
            "def_name": "OutlanderCivil",
            "name": "Western Haderia",
            "is_player": false,
            "relation": "Neutral",
            "goodwill": 0
        },
        {
            "load_id": 1,
            "def_name": "TribeCivil",
            "name": "Coalition of Tol",
            "is_player": false,
            "relation": "Neutral",
            "goodwill": 0
        },
        {
            "load_id": 2,
            "def_name": "Empire",
            "name": "Empire of Mophoos",
            "is_player": false,
            "relation": "Neutral",
            "goodwill": 0
        },
        {
            "load_id": 3,
            "def_name": "PlayerColony",
            "name": "New Arrivals",
            "is_player": true,
            "relation": "",
            "goodwill": 0
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:21:17.8272328Z"
}

GET


/api/v1/faction/relations

¶

Retrieves the diplomatic relationship status between selected by id faction and all other factions.

curl --request GET \
--url http://localhost:8765/api/v1/faction/relations?id=2

{
    "label": "lowercase label",
    "message": "uppercase message",
    "letter_def": "NeutralEvent"
}

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

GET


/api/v1/faction/player

¶

Returns detailed information about the player's own faction.

Example:

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

Response:

{
    "success": true,
    "data": {
        "load_id": 3,
        "def_name": "PlayerColony",
        "name": "New Arrivals",
        "is_player": true,
        "leader_title": "Spirit Speaker",
        "leader_id": 0
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:22:33.5209596Z"
}

GET


/api/v1/faction

¶

Retrieves detailed information about a specific faction identified by id.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/faction?id=2'

Response:

{
    "success": true,
    "data": {
        "load_id": 2,
        "def_name": "Empire",
        "name": "Empire of Mophoos",
        "is_player": false,
        "leader_title": "High Stellarch",
        "leader_id": 969
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:23:10.8428989Z"
}

GET


/api/v1/faction/relation-with

¶

Gets the diplomatic relationship status between two specified factions.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/faction/relation-with?id=2&other_id=1'

Response:

{
    "success": true,
    "data": {
        "goodwill": 0,
        "relation_kind": "Neutral"
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:25:02.2515491Z"
}

GET


/api/v1/faction/def

¶

Fetches the raw definition data (Def) for a faction.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/faction/def?name=OutlanderCivil'

Response:

{
    "success": true,
    "data": {
        "def_name": "OutlanderCivil",
        "pawn_singular": "outlander",
        "pawns_plural": "outlanders",
        "leader_title": "prime councilor",
        "category_tag": "Outlander",
        "hostile_to_factionless_humanlikes": false,
        "starting_count_at_world_creation": "1",
        "permanent_enemy": false,
        "natural_enemy": false,
        "classic_ideo": true,
        "hidden_ideo": false,
        "can_siege": true,
        "can_stage_attacks": true,
        "can_use_avoid_grid": true,
        "can_psychic_ritual_siege": false,
        "earliest_raid_days": 0.0
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:34:20.6487856Z"
}

POST


/api/v1/faction/change/goodwill

¶

Manually change the goodwill value between two factions by a specified amount.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/faction/change/goodwill \
--header 'content-type: application/json' \
--data '{
    "id": 0,
    "other_id": 2,
    "value": -30,
    "send_message": false,
    "can_send_hostility_letter": false
}'

Request:

{
    "id": 0,
    "other_id": 2,
    "value": -30,
    "send_message": false,
    "can_send_hostility_letter": false
}

Response:

{
    "success": true,
    "data": {
        "goodwill": 0,
        "relation_kind": "Neutral"
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:25:02.2515491Z"
}

GET


/api/v1/faction/icon

¶

Retrieves the visual icon and primary color associated with a specific faction. The image is returned as a Base64 encoded string (PNG format), suitable for direct embedding in web frontends.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/faction/icon?id=12"

Response:

{
    "success": true,
    "data": {
        "image": {
            "result": "Success",
            "image_base_64": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AA..."
        },
        "color": "#9A2A2A"
    },
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

POST


/api/v1/faction/goodwill

¶

Sets the goodwill value between two factions.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/faction/goodwill \
--header 'content-type: application/json' \
--data '{
    "id": 0,
    "other_id": 2,
    "value": 50
}'

Request:

{
    "id": 0,
    "other_id": 2,
    "value": 50
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

Research Controller¶

Manages the scientific progress of the colony. This controller allows for viewing the current tech tree status and instantly unlocking technologies.

GET


/api/v1/research/progress

¶

Retrieves information about the currently active research project, including its progress, required research points, and status.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/research/progress'

Response:

{
    "success": true,
    "data": {
        "name": "Microelectronics",
        "label": "Microelectronics",
        "progress": 500,
        "research_points": 3000,
        "description": "Build advanced components and electronics.",
        "is_finished": false,
        "can_start_now": true,
        "player_has_any_appropriate_research_bench": true,
        "required_analyzed_thing_count": 0,
        "analyzed_things_completed": 0,
        "tech_level": "Industrial",
        "prerequisites": ["Electricity"],
        "hidden_prerequisites": [],
        "required_by_this": ["Fabrication", "AdvancedMachining"],
        "progress_percent": 0.16666667
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-12T10:00:00.0000000Z"
}

GET


/api/v1/research/finished

¶

Retrieves a list of all research projects that have been successfully completed by the player.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/research/finished'

Response:

{
    "success": true,
    "data": {
        "finished_projects": [
            "electricity",
            "basic_research",
            "stonecutting"
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-12T10:00:00.0000000Z"
}

GET


/api/v1/research/tree

¶

Retrieves the entire research tree, providing a list of all research projects and their details, including prerequisites and tech levels. This can be used to visualize or analyze research progression.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/research/tree'

Response:

{
    "success": true,
    "data": {
        "projects": [
            {
                "name": "basic_research",
                "label": "basic research",
                "progress": 0,
                "research_points": 500,
                "description": "unlocks basic research capabilities.",
                "is_finished": true,
                "can_start_now": false,
                "player_has_any_appropriate_research_bench": true,
                "required_analyzed_thing_count": 0,
                "analyzed_things_completed": 0,
                "tech_level": "neolithic",
                "prerequisites": [],
                "hidden_prerequisites": [],
                "required_by_this": ["electricity", "stonecutting"],
                "progress_percent": 1.0
            },
            {
                "name": "electricity",
                "label": "electricity",
                "progress": 0,
                "research_points": 1000,
                "description": "unlocks electrical power generation and basic electrical devices.",
                "is_finished": false,
                "can_start_now": true,
                "player_has_any_appropriate_research_bench": true,
                "required_analyzed_thing_count": 0,
                "analyzed_things_completed": 0,
                "tech_level": "industrial",
                "prerequisites": ["basic_research"],
                "hidden_prerequisites": [],
                "required_by_this": ["microelectronics"],
                "progress_percent": 0.0
            }
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-12T10:00:00.0000000Z"
}

GET


/api/v1/research/project

¶

Retrieves detailed information about a specific research project by its name. This includes its progress, prerequisites, tech level, and description.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/research/project?name=Microelectronics'

Response:

{
    "success": true,
    "data": {
        "name": "Microelectronics",
        "label": "Microelectronics",
        "progress": 500,
        "research_points": 3000,
        "description": "build advanced components and electronics.",
        "is_finished": false,
        "can_start_now": true,
        "player_has_any_appropriate_research_bench": true,
        "required_analyzed_thing_count": 0,
        "analyzed_things_completed": 0,
        "tech_level": "Industrial",
        "prerequisites": ["Electricity"],
        "hidden_prerequisites": [],
        "required_by_this": ["Fabrication", "AdvancedMachining"],
        "progress_percent": 0.16666667
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-12t10:00:00.0000000z"
}

GET


/api/v1/research/summary

¶

Provides a high-level summary of the player's research status, including counts of finished, total, and available projects, and categorization by tech level and research tab.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/research/summary'

Response:

{
    "success": true,
    "data": {
        "finished_projects_count": 3,
        "total_projects_count": 50,
        "available_projects_count": 15,
        "by_tech_level": {
            "neolithic": {
                "finished": 1,
                "total": 5,
                "percent_complete": 20.0,
                "projects": ["BasicResearch"]
            },
            "industrial": {
                "finished": 2,
                "total": 10,
                "percent_complete": 20.0,
                "projects": ["Electricity", "Stonecutting"]
            }
        },
        "by_tab": {
            "basic": {
                "finished": 2,
                "total": 10,
                "percent_complete": 20.0,
                "projects": ["BasicResearch", "Stonecutting"]
            },
            "power": {
                "finished": 1,
                "total": 5,
                "percent_complete": 20.0,
                "projects": ["electricity"]
            }
        }
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-12T10:00:00.0000000Z"
}

POST


/api/v1/research/target

¶

Set the colony's active research project by its defName. This immediately redirects the colony's research focus.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/research/target?name=Electricity&force=false'

Response:

{
    "success": true,
    "data": {
        "finished_projects_count": 3,
        "total_projects_count": 50,
        "available_projects_count": 15,
        "by_tech_level": {
            "neolithic": {
                "finished": 1,
                "total": 5,
                "percent_complete": 20.0,
                "projects": ["BasicResearch"]
            },
            "industrial": {
                "finished": 2,
                "total": 10,
                "percent_complete": 20.0,
                "projects": ["Electricity", "Stonecutting"]
            }
        },
        "by_tab": {
            "basic": {
                "finished": 2,
                "total": 10,
                "percent_complete": 20.0,
                "projects": ["BasicResearch", "Stonecutting"]
            },
            "power": {
                "finished": 1,
                "total": 5,
                "percent_complete": 20.0,
                "projects": ["electricity"]
            }
        }
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2026-03-28T16:10:00.0000000Z"
}

POST


/api/v1/research/stop

¶

Stop the colony's currently active research project. This unassigns the research focus and returns the state of the project that was halted. Returns an error if no research is currently active.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/research/stop'

Response:

{
  "success": true,
  "errors": [],
  "warnings": [],
  "timestamp": "2026-02-18T13:22:46.312391Z"
}

⚙️ Game State & Mechanics API¶

Game Controller¶

GET /api/v1/game/state ¶

POST /api/v1/game/speed ¶

GET /api/v1/game/settings/run-in-background ¶

POST /api/v1/game/settings/toggle/run-in-background ¶

GET /api/v1/version ¶

GET /api/v1/mods/list ¶

GET /api/v1/mods/info ¶

GET /api/v1/mods/preview ¶

POST /api/v1/mods/configure ¶

POST /api/v1/select ¶

POST /api/v1/deselect ¶

POST /api/v1/open-tab ¶

GET /api/v1/def/all ¶

POST /api/v1/game/select-area ¶

POST /api/v1/game/send/letter ¶

POST /api/v1/game/save ¶

POST /api/v1/game/load ¶

POST /api/v1/game/start/devquick ¶

POST /api/v1/game/start ¶

GET /api/v1/game/settings ¶

POST /api/v1/game/main-menu ¶

POST /api/v1/game/quit ¶

Game Events Controller¶

GET /api/v1/quests ¶

GET /api/v1/incidents ¶

GET /api/v1/lords ¶

GET /api/v1/incidents/top ¶

GET /api/v1/incident/chance ¶

POST /api/v1/incident/trigger ¶

Faction Controller¶

GET /api/v1/factions ¶

GET /api/v1/faction/relations ¶

GET /api/v1/faction/player ¶

GET /api/v1/faction ¶

GET /api/v1/faction/relation-with ¶

GET /api/v1/faction/def ¶

POST /api/v1/faction/change/goodwill ¶

GET /api/v1/faction/icon ¶

POST /api/v1/faction/goodwill ¶

Research Controller¶

GET /api/v1/research/progress ¶

GET /api/v1/research/finished ¶

GET /api/v1/research/tree ¶

GET /api/v1/research/project ¶

GET /api/v1/research/summary ¶

POST /api/v1/research/target ¶

POST /api/v1/research/stop ¶

GET

`/api/v1/game/state` ¶

POST

`/api/v1/game/speed` ¶

GET

`/api/v1/game/settings/run-in-background` ¶

POST

`/api/v1/game/settings/toggle/run-in-background` ¶

GET

`/api/v1/version` ¶

GET

`/api/v1/mods/list` ¶

GET

`/api/v1/mods/info` ¶

GET

`/api/v1/mods/preview` ¶

POST

`/api/v1/mods/configure` ¶

POST

`/api/v1/select` ¶

POST

`/api/v1/deselect` ¶

POST

`/api/v1/open-tab` ¶

GET

`/api/v1/def/all` ¶

POST

`/api/v1/game/select-area` ¶

POST

`/api/v1/game/send/letter` ¶

POST

`/api/v1/game/save` ¶

POST

`/api/v1/game/load` ¶

POST

`/api/v1/game/start/devquick` ¶

POST

`/api/v1/game/start` ¶

GET

`/api/v1/game/settings` ¶

POST

`/api/v1/game/main-menu` ¶

POST

`/api/v1/game/quit` ¶

GET

`/api/v1/quests` ¶

GET

`/api/v1/incidents` ¶

GET

`/api/v1/lords` ¶

GET

`/api/v1/incidents/top` ¶

GET

`/api/v1/incident/chance` ¶

POST

`/api/v1/incident/trigger` ¶

GET

`/api/v1/factions` ¶

GET

`/api/v1/faction/relations` ¶

GET

`/api/v1/faction/player` ¶

GET

`/api/v1/faction` ¶

GET

`/api/v1/faction/relation-with` ¶

GET

`/api/v1/faction/def` ¶

POST

`/api/v1/faction/change/goodwill` ¶

GET

`/api/v1/faction/icon` ¶

POST

`/api/v1/faction/goodwill` ¶

GET

`/api/v1/research/progress` ¶

GET

`/api/v1/research/finished` ¶

GET

`/api/v1/research/tree` ¶

GET

`/api/v1/research/project` ¶

GET

`/api/v1/research/summary` ¶

POST

`/api/v1/research/target` ¶

POST

`/api/v1/research/stop` ¶