{"openapi":"3.1.0","info":{"title":"Kairom tools","version":"0.2.0","description":"Kairom, a complex-systems data, simulation and decision engine: system layers (energy, telecom, transport, supply, economy, society, health, regulation), what a site depends on, the workspace's projects and watch targets, what-if simulations of strikes, outages, supplier failure, cyber and price shocks, and weather hazards as one input among many. Authenticate with `Authorization: Bearer <key>` (workspace keys from the app's API keys page). Quote each response's status, as_of, ranges and caveats; never give numbers that are not in a response. Decision support only; official warnings take precedence. The same tools are available as an MCP server at /mcp and as the versioned REST API /api/v2."},"servers":[{"url":"http://kairom.world"}],"paths":{"/api/tools/list_layers":{"get":{"operationId":"list_layers","summary":"List layers","description":"START HERE. The systems Kairom models, as data layers: energy grid, fuel, telecom and digital, cyber, road and rail/ports, trade and supply chains, economy by sector, people and crowd events, calendars, health surveillance, regulation, built environment. Per layer: what it covers, refresh, licence, status (validated / screening / experimental), what it can answer (site dependencies, map, watch metrics, shocks, non-weather scenarios such as strikes, supplier failure, outages, cyber, price and regulation shocks) and its watch metric ids for layer_metric. Use it to frame a decision in terms of the systems a person or organisation depends on; weather hazards are one further input (hazard tools). Limits: coverage differs per layer (several are Spain-first, others EU-wide); most layers are screening, some experimental; quote each layer's status.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"group","in":"query","required":false,"description":"Only layers of this group.","schema":{"type":"string","enum":["energy","telecom","digital","cyber","transport","logistics","supply","economy","society","health","regulation","built"]}}]}},"/api/tools/site_dependencies":{"get":{"operationId":"site_dependencies","summary":"Site dependencies","description":"What a site depends on, across every system layer: the substation that feeds it and its redundancy, access roads and alternatives, nearest port/rail, telecom redundancy, fuel supply, supplier countries and chokepoints, sector exposure of the local economy, crowd events and calendars, regulation and cyber exposure for its sector; plus the merged dependency list with single points of failure. Give lat+lon, or project_id (+ site) to use a project's site and its profile. Good for: 'what could stop this warehouse / plant / shop, and is there a backup'. Answers within ~8 s; a layer slower than that is listed as pending (it finishes in the background: call again a minute later for it); repeated places answer in about a second. Limits: open-data screening (OSM topology, public registers); a layer that cannot answer is listed with its reason; not an engineering survey.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"lat","in":"query","required":false,"description":"Latitude, decimal degrees (WGS84).","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","in":"query","required":false,"description":"Longitude, decimal degrees (WGS84).","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"project_id","in":"query","required":false,"description":"Project id from list_projects (this key's workspace only).","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}},{"name":"site","in":"query","required":false,"description":"Site index (0-based, as text) or label within the project; default the first located site.","schema":{"type":"string","maxLength":120}},{"name":"sector","in":"query","required":false,"description":"NACE section or division of the business (e.g. H, C, C10, G_J, 49.41): sector exposure, cyber and regulation context.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.]{1,10}$"}}]}},"/api/tools/layer_metric":{"get":{"operationId":"layer_metric","summary":"Layer metric","description":"Current value of one system-layer metric for a place, a business sector or a country: e.g. electricity_price_eur_mwh or grid_stress_index (country), fuel_price_eur_l near a site, road_access_closed / road_incident_near for a site, port_stoppage, supplier_risk_change, commodity_change_3m_pct (give commodity: brent, gas_eu, wheat, urea, ...) or reg_items_sector for a sector, kev_new_critical_sector (cyber), resp_wave_index (health), crowd_events_nearby, holiday_ahead. Metric ids and their scope (site / sector / country) come from list_layers. Returns value, unit, as_of, a compact detail, the layer's status and source. Limits: coverage differs per layer (several are Spain-first); a layer that cannot answer says why (available=false).","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"layer","in":"query","required":true,"description":"Layer id from list_layers (e.g. energy_grid, road_live, trade_supply, fuel, cyber).","schema":{"type":"string","pattern":"^[a-z0-9_]{2,40}$"}},{"name":"metric","in":"query","required":true,"description":"Watch metric id of that layer (see list_layers).","schema":{"type":"string","pattern":"^[a-z0-9_]{2,60}$"}},{"name":"lat","in":"query","required":false,"description":"Latitude, decimal degrees (WGS84).","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","in":"query","required":false,"description":"Longitude, decimal degrees (WGS84).","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"project_id","in":"query","required":false,"description":"Project id from list_projects (this key's workspace only).","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}},{"name":"site","in":"query","required":false,"description":"Site index (0-based, as text) or label within the project; default the first located site.","schema":{"type":"string","maxLength":120}},{"name":"country","in":"query","required":false,"description":"ISO-2 country (for country-scope metrics).","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"sector","in":"query","required":false,"description":"NACE section or division of the business (e.g. H, C, C10, G_J, 49.41): sector exposure, cyber and regulation context.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.]{1,10}$"}},{"name":"product","in":"query","required":false,"description":"Fuel product (fuel layer).","schema":{"type":"string","enum":["diesel","gasoline95","gasoline98","lpg"]}},{"name":"km","in":"query","required":false,"description":"Search radius in km where the metric uses one (crowd events, roads).","schema":{"type":"number","minimum":0.5,"maximum":50}},{"name":"commodity","in":"query","required":false,"description":"Commodity for economy_sector commodity metrics (brent, gas_eu, wheat, maize, urea, iron_ore, aluminium, copper, zinc, rice, ...): required by commodity_change_3m_pct and commodity_price.","schema":{"type":"string","pattern":"^[a-z_]{2,20}$"}},{"name":"currency","in":"query","required":false,"description":"Currency for fx_per_eur (USD, GBP, CNY, MXN, BRL, TRY).","schema":{"type":"string","pattern":"^[A-Z]{3}$"}}]}},"/api/tools/layer_map_summary":{"post":{"operationId":"layer_map_summary","summary":"Layer map summary","description":"Compact summary of one system layer's map features in an area (counts by type and category, a few sample features with rounded positions, legend), never the raw GeoJSON: e.g. substations and lines around a site (energy_grid), road incidents (road_live), ports and rail (rail_ports), fuel stations (fuel), masts (telecom_digital), crowd events (people), building footprints (built_catastro). Area: lat+lon+radius_km (<= 30 km), bbox (<= 1 square degree) or a project_id (its located sites). Limits: open data (OSM, public registers) can be incomplete; positions are rounded; at most 10 sample features.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"layer":{"type":"string","pattern":"^[a-z0-9_]{2,40}$","description":"Layer id from list_layers (e.g. energy_grid, road_live, trade_supply, fuel, cyber)."},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude, decimal degrees (WGS84)."},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude, decimal degrees (WGS84)."},"radius_km":{"type":"number","minimum":0.5,"maximum":30.0,"description":"Radius in km (default 5)."},"bbox":{"type":"array","items":{"type":"number"},"minItems":4,"maxItems":4,"description":"[west, south, east, north] in degrees, at most 1 square degree."},"project_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$","description":"Project id from list_projects (this key's workspace only)."}},"additionalProperties":false}}}}}},"/api/tools/list_projects":{"get":{"operationId":"list_projects","summary":"List projects","description":"The projects of THIS key's workspace (never another workspace): id, name, type, country, number of sites (located, with a profile), what it watches. Use a project id with get_project, project_dependencies, get_watch, site_dependencies or run_simulation (area {project}). Limits: needs the projects:read scope and a workspace key; at most 100 projects; no notes, addresses or free text are returned.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[]}},"/api/tools/get_system_map":{"get":{"operationId":"get_system_map","summary":"Get system map","description":"START HERE for a company project. Its cross-system map: the chains that can HURT it (risks) and the ones that can HELP it (opportunities), each as trigger -> systems -> sector -> the company (e.g. a port strike -> late inputs -> lost output; a price drop in an input -> margin), with the steps and their values, the simulated impact range (p10/p50/p90, regional GVA, not the company's books), lead time, exposure and plausibility with their basis, the live signal to watch and its current value, the systems by exposure and the recommendations. Families: price and supply, energy, policy and regulation, labour, logistics and infrastructure, demand, cyber, health, and weather as one family among them. Limits: only projects that carry a map (company projects prepared by Kairom; list_projects shows has_system_map); every chain result is experimental; exposure and plausibility are analyst priors, not model outputs.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"project_id","in":"query","required":true,"description":"Project id from list_projects (this key's workspace only).","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}},{"name":"lang","in":"query","required":false,"description":"Language of titles and texts (default en). Structured fields are language-free.","schema":{"type":"string","enum":["en","es","ca"]}},{"name":"max_risks","in":"query","required":false,"description":"Risk chains to return (default 8).","schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"max_opportunities","in":"query","required":false,"description":"Opportunity chains to return (default 4).","schema":{"type":"integer","minimum":0,"maximum":8}}]}},"/api/tools/project_summary":{"get":{"operationId":"project_summary","summary":"Project summary","description":"What Kairom found for one project, in 2-4 plain sentences plus up to 3 key facts (chips): the top cross-system risk and opportunity chain, the single points of failure several sites share, a watch target's forecast and what is live now. Good for: a first answer to 'how is this project doing'. Limits: needs projects:read; texts are checked against the facts (every number must be in them) and fall back to a fixed template; `pending` names what is still being prepared - call again in a minute.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"project_id","in":"query","required":true,"description":"Project id from list_projects (this key's workspace only).","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}},{"name":"lang","in":"query","required":false,"description":"Language of titles and texts (default en). Structured fields are language-free.","schema":{"type":"string","enum":["en","es","ca"]}}]}},"/api/tools/recent_changes":{"get":{"operationId":"recent_changes","summary":"Recent changes","description":"What changed recently around a project or a point: the workspace's own live events for the project (open incidents, rules that fired, changes in its forecasts), road incidents and closures near its sites from the live traffic feeds, and, for a company project, the current value of each risk chain's signal (power and gas prices, fuel, supplier disruption, new rules, health waves...) with its recent change. Good for: 'what happened this week that affects my sites?'. Limits: road feeds cover the countries listed by list_layers (road_live); workspace events exist only where rules or incidents were set up; signals are screening values, quote as_of.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"project_id","in":"query","required":false,"description":"Project id from list_projects (this key's workspace only).","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}},{"name":"lat","in":"query","required":false,"description":"","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","in":"query","required":false,"description":"","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"days","in":"query","required":false,"description":"Look-back for workspace events (default 7).","schema":{"type":"integer","minimum":1,"maximum":30}},{"name":"km","in":"query","required":false,"description":"Radius for road events around each site (default 15).","schema":{"type":"number","minimum":1,"maximum":50}},{"name":"lang","in":"query","required":false,"description":"Language of titles and texts (default en). Structured fields are language-free.","schema":{"type":"string","enum":["en","es","ca"]}}]}},"/api/tools/get_project":{"get":{"operationId":"get_project","summary":"Get project","description":"One project of this key's workspace: type, country, its sites (label, position rounded to about 100 m, what the owner told us: backup power hours, inventory days, staff per shift, value per day, critical routes, supplier countries and lead times, what it depends on) and what it watches. Limits: what the workspace entered, not verified; no notes, addresses, supplier names or free text; at most 50 sites listed.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"project_id","in":"query","required":true,"description":"Project id from list_projects (this key's workspace only).","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}}]}},"/api/tools/project_dependencies":{"get":{"operationId":"project_dependencies","summary":"Project dependencies","description":"Dependencies of every located site of a project (up to max_sites, default 5): per site the systems it depends on and its single points of failure, plus what several sites share (e.g. the same substation, port, road corridor or supplier country) - a shared dependency is a portfolio-wide risk. Up to ~25 s. Limits: open-data screening; sites that time out are listed as unavailable; at most 10 sites per call.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"project_id","in":"query","required":true,"description":"Project id from list_projects (this key's workspace only).","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}},{"name":"max_sites","in":"query","required":false,"description":"Sites to analyse (default 5).","schema":{"type":"integer","minimum":1,"maximum":10}},{"name":"sector","in":"query","required":false,"description":"NACE section or division of the business (e.g. H, C, C10, G_J, 49.41): sector exposure, cyber and regulation context.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.]{1,10}$"}}]}},"/api/tools/list_watch_sources":{"get":{"operationId":"list_watch_sources","summary":"List watch sources","description":"The signals a watch target can be explained by: each source's id, label, system layer, unit, refresh, scope and whether it has history (power prices, fuel, road incidents, port activity, supplier news, crowd events, calendars, health waves, weather as one source among them). Limits: the list depends on what the watch service has data for; a source with has_history=false cannot be validated as a driver yet.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[]}},"/api/tools/get_watch":{"get":{"operationId":"get_watch","summary":"Get watch","description":"The watch targets of one project of this key's workspace: for each target (e.g. daily orders, deliveries late, staff absence, energy cost) the current value, recent series, the forecast band (p10/p50/p90 over its horizon), the drivers that explain it (source, layer, relation, lag, strength, n), the method, status and validation. Good for: 'what is likely to move my KPI this week and why'. Limits: needs projects:read; series are trimmed to the last 24 points and forecasts to 48 steps; drivers are associations, quote each target's status and validation.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"project_id","in":"query","required":true,"description":"Project id from list_projects (this key's workspace only).","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,40}$"}}]}},"/api/tools/list_simulations":{"get":{"operationId":"list_simulations","summary":"List simulations","description":"What-if simulations. FIRST the systems scenarios of the coupled cascade (sim coupled_cascade): transport/logistics strike, key supplier failure, power and telecom outage, cyber/payment outage, energy and fuel price shocks, regulation change, large crowd event, blackout, rumour wave, epidemic onset - each propagated through infrastructure, services, behaviour, supply chains and the economy with feedback loops; also every layer's own scenario (scenario kind layer_scenario, e.g. trade_supply/supplier_failure, road_live/haulage_strike_es_2022, rail_ports/port_strike). Then the other simulators (logistics, infrastructure cascade, evacuation, epidemic, drought/water, input-output economy) and, as one family, the hazard simulators (flood, wildfire, storm, ...). Each with status (validated / screening / experimental) and an example request for run_simulation. Limits: most simulators are screening or experimental (order of magnitude); horizons are capped for API runs.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"domain","in":"query","required":false,"description":"Only this domain.","schema":{"type":"string","enum":["economy","infrastructure","logistics","society","health","supply","policy","hazard"]}}]}},"/api/tools/run_simulation":{"post":{"operationId":"run_simulation","summary":"Run simulation","description":"Run one simulation and get a compact answer: headline summary with p10/p50/p90 ranges, key moments in time, peaks of the main series, the loss split by driver where the simulator gives one, the site's own view when a project site has a profile, status and the validation block (never frames). Systems examples: sim_id coupled_cascade with scenario {kind: strike | supplier_failure | power_telecom_outage | cyber_outage | price_shock | fuel_price_shock | regulation_change | crowd_event} and area {lat, lon, radius_km} or {country: [\"ES\"]} or {project: id}; or {kind: layer_scenario, id: \"trade_supply/supplier_failure\"}; or a cross-system chain {kind: chain, events: [{kind: heat | storm | rain | snow | drought | tariff | cbam | sanction | labour_rule | regulation | oil | strike | epidemic | cyber, level or magnitude, duration_h, sectors}]} (the answer lists each step: event -> system -> sector). Caps: horizon <= 2880 h, radius <= 50 km, <= 25 regions; runs over ~50 s continue in the background (call again with the same arguments). Needs the simulate scope. Limits: screening/experimental simulators give orders of magnitude - quote the status.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sim_id":{"type":"string","pattern":"^[a-z0-9_]{2,40}$","description":"Simulator id from list_simulations (e.g. coupled_cascade, logistics, infra_cascade)."},"area":{"type":"object","additionalProperties":true,"description":"{\"lat\",\"lon\",\"radius_km\"} | {\"bbox\":[w,s,e,n]} | {\"project\": id, \"site\"?: index} | {\"nuts\":[codes]} | {\"country\":[ISO-2]}"},"scenario":{"type":"object","additionalProperties":true,"description":"e.g. {\"kind\": \"strike\"}, {\"kind\": \"supplier_failure\", \"scale\": 1.5}, {\"kind\": \"layer_scenario\", \"id\": \"rail_ports/port_strike\"}, {\"kind\": \"chain\", \"events\": [{\"kind\": \"heat\", \"level\": 2, \"sectors\": [\"F\"]}]}"},"horizon_h":{"type":"integer","minimum":1,"maximum":2880,"description":"Hours to simulate (default: the simulator's own)."},"params":{"type":"object","additionalProperties":true,"description":"Simulator-specific parameters (see list_simulations / the app)."}},"additionalProperties":false}}}}}},"/api/tools/explain_view":{"post":{"operationId":"explain_view","summary":"Explain view","description":"Explain one Kairom view (a project, the map, an incident, a simulation result...) from a compact context you pass: a short summary of what matters for decisions, systems, money and people, through the Kairom assistant. Every number and every place, system or state in the answer is checked against your context; unsupported sentences are removed. Good for: turning a Kairom API response into a briefing. Limits: it explains only what the context holds (send the key numbers, at most 16 KB); decision support, not an official warning.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"view":{"type":"string","enum":["home","projects","project","map","systems","simulations","sim_result","live","incident","track","developers","settings"],"description":"Which view the context comes from (e.g. project, map, incident, sim_result)."},"context":{"type":"object","additionalProperties":true,"description":"Compact JSON of what is on screen or in an API response (<= 16 KB)."},"title":{"type":"string","maxLength":200,"description":"Optional title (project, incident or simulator name)."},"lang":{"type":"string","enum":["en","es","ca"],"description":"Answer language (default en)."},"focus":{"type":"object","description":"Optional: one element of the view to explain instead of the whole view (1-2 sentences).","properties":{"label":{"type":"string","maxLength":120,"description":"Short name of the element (e.g. 'Expected loss')."},"kind":{"type":"string","maxLength":24,"description":"chart, chart-point, map-feature, table-row, card, element..."},"text":{"type":"string","maxLength":1500,"description":"Its visible text."},"ctx":{"type":"object","additionalProperties":true,"description":"Its numbers and ids (<= 4 KB)."}}}},"additionalProperties":false}}}}}},"/api/tools/impact_outlook":{"post":{"operationId":"impact_outlook","summary":"Impact outlook","description":"Weather and natural hazards, ONE INPUT AMONG MANY (for systems, dependencies and non-weather shocks use list_layers, site_dependencies and run_simulation first). Consequences of a hazard in a European region, in one answer: money (economic loss EUR m, p10/p50/p90, split direct / business interruption / indirect), people (excess deaths, hospital pressure, lost working hours) and the likely institutional response (national declaration, Copernicus EMS, EU Solidarity Fund eligibility and aid range, who legally must act). Give lat+lon or an ISO-2 country, optionally the hazard and the physical outcome you want priced (damage_eur_m, people_affected, harmed, person_h_no_power, outage_hours; heat: daily_mean_t and daily_max_t lists + start). Without outcome numbers it falls back to the live run's expected people at orange and fills only what needs no damage estimate. Every block says `available`, `label`, `skill` (what the back-test showed) and `limits`; quote them. Limits: ECONOMICS IS ORDER OF MAGNITUDE (3-event back-test: model 0.1-1.2x of published losses, depends on how complete the flood footprint is; repeat the range, never one number); MORTALITY RANKS REGIONS WELL BUT UNDER-PREDICTS (about 0.57x of observed heat excess) and exists for heat only; hospital pressure and lost hours are assumption-based; POLICY PROBABILITIES ONLY WHERE THERE IS SKILL: EU Solidarity Fund acceptance (Brier skill +39 %); EUSF application (+3 %) and Copernicus mapping (-3 %) are base rates, national declarations are modelled for France only; eligibility and aid are legal rules. Regional aggregates (NUTS3/NUTS2), not buildings or people; decision support, not a loss assessment or legal advice.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude, decimal degrees (WGS84)."},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude, decimal degrees (WGS84)."},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO-2 country code, whole country (alternative to lat+lon)."},"hazard":{"type":"string","enum":["flood","heat","wildfire","storm","earthquake","coast","wind","fire","drought"],"description":"Hazard type to evaluate."},"damage_eur_m":{"type":"array","items":{"type":"number","minimum":0},"minItems":1,"maxItems":3,"description":"Direct physical damage, EUR million: one value or [p10, p50, p90]."},"people_affected":{"type":"array","items":{"type":"number","minimum":0},"minItems":1,"maxItems":3,"description":"People affected: one value or [p10, p50, p90]."},"harmed":{"type":"array","items":{"type":"number","minimum":0},"minItems":1,"maxItems":3,"description":"People harmed (simulation), one value or [p10, p50, p90]."},"person_h_no_power":{"type":"array","items":{"type":"number","minimum":0},"minItems":1,"maxItems":3,"description":"Person-hours without electricity, one value or [p10, p50, p90]."},"outage_hours":{"type":"number","minimum":0,"maximum":10000,"description":"Duration of the longest power or water failure, hours (unrest screen)."},"daily_mean_t":{"type":"array","items":{"type":"number","minimum":-60,"maximum":60},"minItems":1,"maxItems":30,"description":"Heat: daily mean temperature, degC, one entry per day."},"daily_max_t":{"type":"array","items":{"type":"number","minimum":-60,"maximum":60},"minItems":1,"maxItems":30,"description":"Heat: daily maximum temperature, degC, same days."},"start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date of the first day (heat), YYYY-MM-DD."}},"additionalProperties":false}}}}}},"/api/tools/hazard_outlook":{"get":{"operationId":"hazard_outlook","summary":"Hazard outlook","description":"Weather and natural hazards, ONE INPUT AMONG MANY (for systems, dependencies and non-weather shocks use list_layers, site_dependencies and run_simulation first). Probabilistic hazard outlook for a point in Europe, from the Kairom live engine (51-member ECMWF ensemble plus GloFAS river, CMEMS sea level/waves, CAMS air, EFFIS/FIRMS fire, EDO drought, and `flash_flood`: ensemble rain vs small-catchment (5-500 km2) flash / pluvial flood thresholds; marked experimental=true while it has not passed its validation). Give lat+lon or an address (or iso2 for a country summary, EU for Europe). Returns, for the windows 0-24, 24-48, 48-72 and 72-144 h, the worst level (yellow/orange/red), per-hazard probability with its 90 % range and threshold units, top hazards, expected people exposed, the issue time, data age and the status of every live feed, plus `reported_impacts`: media/official reports (links, unverified) near the point in the last 24 h. Good for: 'what weather risk is there at X in the next days'. Limits: Europe domain only (point must be within 40 km of a grid cell, about 25-250 km2 cells, not a parcel); thresholds are pan-European defaults, not national warning criteria (uncalibrated; see engine_track_record); probabilities are ensemble shares and under-dispersive; fire is deterministic (p is 0 or 1); expected people is exposure, not casualties. Official warnings take precedence. Address lookup sends the text to a public geocoder.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"lat","in":"query","required":false,"description":"Latitude, decimal degrees (WGS84).","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","in":"query","required":false,"description":"Longitude, decimal degrees (WGS84).","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"address","in":"query","required":false,"description":"Street address or place name (geocoded with public geocoders).","schema":{"type":"string","minLength":3,"maxLength":200}},{"name":"iso2","in":"query","required":false,"description":"Instead of a point: ISO-2 country code (GB for the UK, GR for Greece) for the country summary (totals, expected people at orange or worse, the most affected cells), or EU for the Europe-wide top countries and cells.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}}]}},"/api/tools/site_risk_report":{"post":{"operationId":"site_risk_report","summary":"Site risk report","description":"Weather and natural hazards, ONE INPUT AMONG MANY (for systems, dependencies and non-weather shocks use list_layers, site_dependencies and run_simulation first). Site risk report for a house or plot: river, coastal and surface flood (with the legal hydraulic zone in Spain), wildfire, heat and other hazards, each with a verdict, Monte Carlo uncertainty ranges split by source, ranked questions that would narrow the uncertainty, due-diligence checklist and the engine's live status. Give an address or lat+lon, optionally the user's answers (floor_level, door_height_m, flooded_before, ...) and call again to narrow the ranges. SLOW: 15-60 s the first time for a place (open data are read remotely), cached for one hour; at most two run at once per instance (a 'busy' error means retry in 15 s). Limits: calibrated and checked for Spain only; elsewhere in Europe it uses Europe static layers at 36-253 km2 cell level plus point models and says it is not validated nationally; modelled, not the official flood delimitation; not a survey, valuation or insurance quote. The address is sent to public geocoders and (Spain) the Catastro; do not pass other personal data.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","minLength":3,"maxLength":200,"description":"Street address or place name (geocoded with public geocoders)."},"lat":{"type":"number","minimum":27,"maximum":72,"description":"Latitude (Europe)."},"lon":{"type":"number","minimum":-32,"maximum":45,"description":"Longitude (Europe)."},"answers":{"type":"object","description":"Optional facts the user knows; keys: floor_level, door_height_m, flooded_before, years_known, defence_rp, refcat, height_above_river_m, building_year","properties":{"floor_level":{"type":"string","enum":["basement","ground","1","2","3","4","5","6"],"description":"Floor of the home."},"door_height_m":{"type":"number","minimum":-3,"maximum":20,"description":"Height of the door sill above the street, m."},"flooded_before":{"type":"boolean","description":"Has the place been flooded before?"},"years_known":{"type":"number","minimum":1,"maximum":100,"description":"Years the user has known the place."},"defence_rp":{"type":"number","minimum":2,"maximum":1000,"description":"Return period (years) the local flood defence is built for."},"refcat":{"type":"string","minLength":14,"maxLength":20,"description":"Spanish cadastral reference."},"height_above_river_m":{"type":"number","minimum":-20,"maximum":100,"description":"Height of the ground above the river bank, m."},"building_year":{"type":"integer","minimum":1700,"maximum":2030,"description":"Year the building was built."}},"additionalProperties":false}},"additionalProperties":false}}}}}},"/api/tools/engine_track_record":{"get":{"operationId":"engine_track_record","summary":"Engine track record","description":"Weather and natural hazards, ONE INPUT AMONG MANY (for systems, dependencies and non-weather shocks use list_layers, site_dependencies and run_simulation first). Measured reliability of the Kairom Europe engine: verification scores of its forecasts against observed events (MeteoAlarm warnings, Copernicus EMS flood activations, FIRMS fire detections, station heat/cold). Per country (or ALL) and hazard: events, hit rate (pod), false-alarm ratio (far), Brier skill (bss), AUC, with a status flag when there are too few events. Use it to say how much to trust an outlook. Limits: scores come from a few issues (one weather situation so far), so per-country figures are indicative; the national-threshold calibration is not yet validated; rows flagged 'insufficient' (under 10 events) must not be quoted as skill. The result also carries replay_headline: the multi-year replay (2023-2026) per hazard, pooled Europe POD/FAR/BSS/AUC/events and per-country yellow BSS (insufficient countries listed apart). Filter with country (ISO-2 or ALL) and hazard (rain, wind, snow, heat, cold, fire, river_flood).","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"country","in":"query","required":false,"description":"ISO-2 code or ALL (default ALL).","schema":{"type":"string","pattern":"^([A-Za-z]{2}|ALL|all)$"}},{"name":"hazard","in":"query","required":false,"description":"Only this hazard.","schema":{"type":"string","enum":["rain","wind","snow","heat","cold","fire","river_flood"]}}]}},"/api/tools/who_can_act":{"get":{"operationId":"who_can_act","summary":"Who can act","description":"Who is legally able or obliged to act (owner, legal basis, who must agree) on a hazard in a European country, from Kairom's decision catalogue (src/europe/decisions): per action the owner (authority or operator), authority level, who must agree, legal basis with citation, obligation (mandatory/optional), availability, the trigger and a verification status. Good for: 'who decides on evacuation / road closure / warning in Austria?'. Limits: a research catalogue, NOT legal advice; items marked unverified or secondary must be checked by a lawyer of the country; coverage is the countries listed in the result's coverage and, for some, only some regions (see note); no costs or effects are quoted. Filter by action_type (free text matched against action id, label, hazard, owner, trigger, e.g. 'evacuation', 'heat', 'road').","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"country","in":"query","required":true,"description":"ISO-2 country code (EU for the EU-level layer).","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"action_type","in":"query","required":false,"description":"Optional free-text filter, e.g. evacuation, warning, school, heat, road.","schema":{"type":"string","maxLength":60}}]}},"/api/tools/sources_and_licences":{"get":{"operationId":"sources_and_licences","summary":"Sources and licences","description":"The data sources behind Kairom and the attribution each requires (ECMWF open data, Copernicus EMS/CAMS/CMEMS/GloFAS/EFAS, EFFIS, NASA FIRMS, MeteoAlarm, national geocoders and others) with their licences. Good for: citing the data correctly when you pass Kairom numbers on. Limits: the list is parsed from the project's licence audit (docs/sources.md); it states the licence class, not legal advice. Set full=true for the complete source inventory.","security":[{"bearerAuth":[]},{"passcode":[]}],"responses":{"200":{"description":"Compact JSON with units, issue time, data age, uncertainty ranges and source.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Bad input."},"401":{"description":"Missing or invalid key."},"404":{"description":"Nothing found."},"429":{"description":"Rate limited (see Retry-After)."},"503":{"description":"Data not available or busy."}},"parameters":[{"name":"full","in":"query","required":false,"description":"Include the full inventory of sources (default false: attribution credits only).","schema":{"type":"boolean"}}]}}},"x-tool-order":["list_layers","site_dependencies","layer_metric","layer_map_summary","list_projects","get_system_map","project_summary","recent_changes","get_project","project_dependencies","list_watch_sources","get_watch","list_simulations","run_simulation","explain_view","impact_outlook","hazard_outlook","site_risk_report","engine_track_record","who_can_act","sources_and_licences"],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"passcode":{"type":"apiKey","in":"header","name":"X-Passcode"}}}}