{"openapi":"3.0.0","info":{"title":"Age of Empires II Battle Simulator API","description":"API for simulating battles, retrieving unit stats, and running scenarios.","version":"0.2.0"},"servers":[{"url":"https://aoe2-battlesim.thecodeartist.workers.dev"}],"paths":{"/simulate":{"post":{"summary":"Run a single battle simulation between two army specs using the v1 generic catalog.","description":"Run a single battle simulation between two army specs using the v1 generic catalog. Returns: winner (\"side_a\"|\"side_b\"|null for draw), draw (bool), duration_s, per-side remaining_count/remaining_hp/hp_pct_remaining/resource_value_initial/resource_value_remaining/resource_value_lost, and efficiency ratios. Call list_presets or list_units first if you do not know a valid unit key. For civ-specific Imperial/Castle/Feudal stats use simulate_v2 instead — it uses the full AoE2 armor-class damage formula, per-civ tech bonuses, trample, and accuracy, making it a significantly more accurate model of the actual game.","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["side_a","side_b"],"additionalProperties":false,"properties":{"side_a":{"type":"object","description":"Army A specification.","additionalProperties":false,"required":["unit"],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}},"side_b":{"type":"object","description":"Army B specification.","additionalProperties":false,"required":["unit"],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}},"options":{"type":"object","description":"Simulation options.","additionalProperties":false,"properties":{"include_history":{"type":"boolean","description":"Include tick-by-tick history in the result (default false)."},"tick":{"type":"number","minimum":0.001,"description":"Simulation time step in seconds (default 0.05)."},"maxDuration":{"type":"number","minimum":1,"description":"Maximum simulation duration in seconds (default 300)."}}}}}}}}}},"/simulate/v2":{"post":{"summary":"Run a single battle simulation using the v2 engine with civ-specific unit data.","description":"Run a single battle simulation using the v2 engine with civ-specific unit data. Unit keys are civ-prefixed (e.g. \"britons_cavalier\", \"aztecs_eagle_warrior\"). Uses the full AoE2 armor-class damage formula and supports trample (blastDamage). Supports accuracy modelling via options.accuracy:true (ranged units can miss). Returns the same fields as simulate. Call GET /v2/units to discover valid keys.","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["side_a","side_b"],"additionalProperties":false,"properties":{"side_a":{"type":"object","description":"Army A — unit key must be a v2 civ-prefixed key.","additionalProperties":false,"required":["unit"],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}},"side_b":{"type":"object","description":"Army B — unit key must be a v2 civ-prefixed key.","additionalProperties":false,"required":["unit"],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}},"options":{"type":"object","description":"Simulation options.","additionalProperties":false,"properties":{"include_history":{"type":"boolean","description":"Include tick-by-tick history in the result (default false)."},"tick":{"type":"number","minimum":0.001,"description":"Simulation time step in seconds (default 0.05)."},"maxDuration":{"type":"number","minimum":1,"description":"Maximum simulation duration in seconds (default 300)."},"accuracy":{"type":"boolean","description":"Enable accuracy modelling: ranged units deal 0 damage on a miss (default false)."}}}}}}}}}},"/simulate/v2/batch":{"post":{"summary":"Run multiple v2 battle simulations in a single request, each tagged with a caller-supplied id.","description":"Run multiple v2 battle simulations in a single request, each tagged with a caller-supplied id. Unit keys must be v2 civ-prefixed (e.g. \"britons_cavalier\"). Returns an array where each element includes the id plus the same fields as simulate_v2. Call GET /v2/units to discover valid keys.","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["matchups"],"additionalProperties":false,"properties":{"matchups":{"type":"array","description":"Array of matchups to simulate.","items":{"type":"object","required":["side_a","side_b"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Caller-supplied identifier for this matchup."},"side_a":{"type":"object","description":"Army A — unit key must be a v2 civ-prefixed key.","additionalProperties":false,"required":["unit"],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}},"side_b":{"type":"object","description":"Army B — unit key must be a v2 civ-prefixed key.","additionalProperties":false,"required":["unit"],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}}}}},"options":{"type":"object","description":"Simulation options.","additionalProperties":false,"properties":{"include_history":{"type":"boolean","description":"Include tick-by-tick history in the result (default false)."},"tick":{"type":"number","minimum":0.001,"description":"Simulation time step in seconds (default 0.05)."},"maxDuration":{"type":"number","minimum":1,"description":"Maximum simulation duration in seconds (default 300)."},"accuracy":{"type":"boolean","description":"Enable accuracy modelling: ranged units deal 0 damage on a miss (default false)."}}}}}}}}}},"/simulate/v2/sweep":{"post":{"summary":"Sweep a numeric parameter across a range using the v2 engine and report results per step.","description":"Sweep a numeric parameter across a range using the v2 engine and report results per step. Unit keys must be v2 civ-prefixed (e.g. \"britons_cavalier\"). Returns: sweep_param, breakeven (the value where the winner first flips, or null if no flip), and results array of {value, winner} entries. Call GET /v2/units to discover valid keys.","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["side_a","side_b","sweep"],"additionalProperties":false,"properties":{"side_a":{"type":"object","description":"Army A — unit key must be a v2 civ-prefixed key.","additionalProperties":false,"required":["unit"],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}},"side_b":{"type":"object","description":"Army B — unit key must be a v2 civ-prefixed key.","additionalProperties":false,"required":["unit"],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}},"sweep":{"type":"object","description":"Sweep configuration.","required":["target","range"],"additionalProperties":false,"properties":{"target":{"type":"string","description":"Dot-path to the numeric field to sweep.","enum":["side_a.count","side_b.count","side_a.micro","side_b.micro","side_a.engagement_pct","side_b.engagement_pct","side_a.buildings","side_b.buildings","side_a.delay","side_b.delay","side_a.tech_delay","side_b.tech_delay","side_a.units_before","side_b.units_before","side_a.overrides.hp","side_b.overrides.hp","side_a.overrides.patk","side_b.overrides.patk","side_a.overrides.matk","side_b.overrides.matk","side_a.overrides.parm","side_b.overrides.parm","side_a.overrides.marm","side_b.overrides.marm","side_a.overrides.reload","side_b.overrides.reload","side_a.overrides.range","side_b.overrides.range"]},"range":{"type":"object","description":"Numeric range for the sweep.","required":["min","max","step"],"additionalProperties":false,"properties":{"min":{"type":"number","description":"Start value (inclusive)."},"max":{"type":"number","description":"End value (inclusive)."},"step":{"type":"number","minimum":0.001,"description":"Increment between values (must be > 0)."}}}}},"options":{"type":"object","description":"Simulation options.","additionalProperties":false,"properties":{"include_history":{"type":"boolean","description":"Include tick-by-tick history in the result (default false)."},"tick":{"type":"number","minimum":0.001,"description":"Simulation time step in seconds (default 0.05)."},"maxDuration":{"type":"number","minimum":1,"description":"Maximum simulation duration in seconds (default 300)."},"accuracy":{"type":"boolean","description":"Enable accuracy modelling: ranged units deal 0 damage on a miss (default false)."}}}}}}}}}},"/simulate/batch":{"post":{"summary":"Run multiple battle simulations in a single request, each tagged with a caller-supplied id.","description":"Run multiple battle simulations in a single request, each tagged with a caller-supplied id. Returns an array where each element includes the id plus the same fields as simulate. Call list_presets or list_units first if you do not know valid unit keys.","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["matchups"],"additionalProperties":false,"properties":{"matchups":{"type":"array","description":"Array of matchups to simulate.","items":{"type":"object","required":["side_a","side_b"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Caller-supplied identifier for this matchup."},"side_a":{"type":"object","description":"Army specification — unit key reference, key + overrides, or fully inline stats.","additionalProperties":false,"required":["unit"],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}},"side_b":{"type":"object","description":"Army specification — unit key reference, key + overrides, or fully inline stats.","additionalProperties":false,"required":["unit"],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}}}}},"options":{"type":"object","description":"Simulation options.","additionalProperties":false,"properties":{"include_history":{"type":"boolean","description":"Include tick-by-tick history in the result (default false)."},"tick":{"type":"number","minimum":0.001,"description":"Simulation time step in seconds (default 0.05)."},"maxDuration":{"type":"number","minimum":1,"description":"Maximum simulation duration in seconds (default 300)."}}}}}}}}}},"/simulate/sweep":{"post":{"summary":"Sweep a numeric parameter across a range and report results per step.","description":"Sweep a numeric parameter across a range and report results per step. Returns: sweep_param, breakeven (the value where the winner first flips, or null if no flip), and results array of {value, winner} entries. Call list_presets or list_units first if you do not know a valid unit key.","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["side_a","side_b","sweep"],"additionalProperties":false,"properties":{"side_a":{"type":"object","description":"Army specification — unit key reference, key + overrides, or fully inline stats.","additionalProperties":false,"required":["unit"],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}},"side_b":{"type":"object","description":"Army specification — unit key reference, key + overrides, or fully inline stats.","additionalProperties":false,"required":["unit"],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}},"sweep":{"type":"object","description":"Sweep configuration.","required":["target","range"],"additionalProperties":false,"properties":{"target":{"type":"string","description":"Dot-path to the numeric field to sweep.","enum":["side_a.count","side_b.count","side_a.micro","side_b.micro","side_a.engagement_pct","side_b.engagement_pct","side_a.buildings","side_b.buildings","side_a.delay","side_b.delay","side_a.tech_delay","side_b.tech_delay","side_a.units_before","side_b.units_before","side_a.overrides.hp","side_b.overrides.hp","side_a.overrides.patk","side_b.overrides.patk","side_a.overrides.matk","side_b.overrides.matk","side_a.overrides.parm","side_b.overrides.parm","side_a.overrides.marm","side_b.overrides.marm","side_a.overrides.reload","side_b.overrides.reload","side_a.overrides.range","side_b.overrides.range"]},"range":{"type":"object","description":"Numeric range for the sweep.","required":["min","max","step"],"additionalProperties":false,"properties":{"min":{"type":"number","description":"Start value (inclusive)."},"max":{"type":"number","description":"End value (inclusive)."},"step":{"type":"number","minimum":0.001,"description":"Increment between values (must be > 0)."}}}}},"options":{"type":"object","description":"Simulation options.","additionalProperties":false,"properties":{"include_history":{"type":"boolean","description":"Include tick-by-tick history in the result (default false)."},"tick":{"type":"number","minimum":0.001,"description":"Simulation time step in seconds (default 0.05)."},"maxDuration":{"type":"number","minimum":1,"description":"Maximum simulation duration in seconds (default 300)."}}}}}}}}}},"/units":{"get":{"summary":"List all base units in the catalog.","description":"List all base units in the catalog. Returns keys suitable for use as the unit field in army specs. Use list_presets for fully-upgraded named configurations.","parameters":[{"name":"name","in":"query","required":false,"schema":{"type":"string","description":"Case-insensitive substring filter on unit name."},"description":"Case-insensitive substring filter on unit name."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/units/{id}":{"get":{"summary":"Get the full stat block for a single base unit by its catalog key.","description":"Get the full stat block for a single base unit by its catalog key.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Unit catalog key (e.g. \"archer\")."},"description":"Unit catalog key (e.g. \"archer\")."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/presets":{"get":{"summary":"List all preset army configurations (fully-upgraded named units for specific ages/civs).","description":"List all preset army configurations (fully-upgraded named units for specific ages/civs). Returns keys suitable for use as the unit field in army specs.","parameters":[{"name":"name","in":"query","required":false,"schema":{"type":"string","description":"Case-insensitive substring filter on preset name."},"description":"Case-insensitive substring filter on preset name."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/presets/{id}":{"get":{"summary":"Get the full stat block for a single preset by its key.","description":"Get the full stat block for a single preset by its key.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Preset key (e.g. \"archer_fu_feudal\")."},"description":"Preset key (e.g. \"archer_fu_feudal\")."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/scenarios":{"get":{"summary":"List all built-in named scenarios with their translated army specs.","description":"List all built-in named scenarios with their translated army specs. Returns ids valid for use in run_scenario.","parameters":[],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/scenarios/{id}/simulate":{"post":{"summary":"Run a named built-in scenario by id, optionally overriding army specs or options.","description":"Run a named built-in scenario by id, optionally overriding army specs or options. Returns the same fields as simulate. Call list_scenarios first to discover valid scenario ids.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"Scenario id.","enum":["militia_vs_scouts","maa_vs_scouts","archers_vs_skirms","champi_vs_scouts","knights_vs_halbs","archer_vs_skirm_mass","champi_scout_vs_fc_cataphract"]},"description":"Scenario id."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"additionalProperties":false,"properties":{"overrides":{"type":"object","description":"Optional overrides for side_a, side_b, or options.","additionalProperties":false,"properties":{"side_a":{"type":"object","description":"Partial army spec merged onto scenario side A — all fields optional.","additionalProperties":false,"required":[],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}},"side_b":{"type":"object","description":"Partial army spec merged onto scenario side B — all fields optional.","additionalProperties":false,"required":[],"properties":{"unit":{"description":"Unit key string (e.g. \"archer_fu_feudal\") or inline stat object. Call list_presets or list_units first if you do not know a valid key.","oneOf":[{"type":"string","description":"Key from the units or presets catalog."},{"type":"object","description":"Fully inline stat object.","required":["name","hp","reload","range"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Unit display name."},"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}}]},"count":{"type":"integer","minimum":1,"description":"Number of units (default 1)."},"overrides":{"type":"object","description":"Stat overrides applied on top of the base unit.","additionalProperties":false,"properties":{"hp":{"type":"number","description":"Hit points per unit."},"patk":{"type":"number","description":"Pierce attack."},"matk":{"type":"number","description":"Melee attack."},"parm":{"type":"number","description":"Pierce armour."},"marm":{"type":"number","description":"Melee armour."},"reload":{"type":"number","description":"Attack reload time in seconds."},"range":{"type":"number","description":"Attack range (0 = melee)."},"bonus_atk":{"type":"number","description":"Bonus attack vs specific unit classes."},"bonus_reduction":{"type":"number","minimum":0,"maximum":1,"description":"Bonus attack reduction factor (0–1 scale)."}}},"engagement_pct":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of units engaging each volley (default 100)."},"micro":{"type":"integer","minimum":0,"maximum":5,"description":"Target-fire micro level: 0 = no micro, 5 = perfect (default 0)."},"delay":{"type":"number","minimum":0,"description":"Start delay in seconds before this army begins producing units (default 0)."},"tech_delay":{"type":"number","minimum":0,"description":"Tech upgrade delay in seconds after pre-queued units (default 0)."},"units_before":{"type":"integer","minimum":0,"description":"Units already queued before the fight starts (default 0)."},"buildings":{"type":"integer","minimum":1,"description":"Number of production buildings (default 1)."},"resource_discounts":{"type":"object","description":"Resource cost discounts as percentages (0–100).","additionalProperties":false,"properties":{"all":{"type":"number","minimum":0,"maximum":100,"description":"Discount applied to all resources."},"food":{"type":"number","minimum":0,"maximum":100,"description":"Food discount."},"wood":{"type":"number","minimum":0,"maximum":100,"description":"Wood discount."},"gold":{"type":"number","minimum":0,"maximum":100,"description":"Gold discount."}}}}},"options":{"type":"object","description":"Simulation options.","additionalProperties":false,"properties":{"include_history":{"type":"boolean","description":"Include tick-by-tick history in the result (default false)."},"tick":{"type":"number","minimum":0.001,"description":"Simulation time step in seconds (default 0.05)."},"maxDuration":{"type":"number","minimum":1,"description":"Maximum simulation duration in seconds (default 300)."}}}}}}}}}}}}}}