{"openapi":"3.1.0","info":{"title":"OpenResilience Power — Public API","version":"0.4.1","summary":"Open data and methodology API for the OpenResilience Power platform.","description":"Open-source platform helping decision-makers in Nigeria and Uganda identify child-critical hospitals, clinics, schools, and water points at risk of power failure, anticipate trigger events, and project the child-impact of investment decisions.  All endpoints are public, read-only, rate-limited at the edge, and do not require authentication. Citation of the source dataset is required under the CC-BY 4.0 licence covering the methodology and data.","contact":{"name":"Tribe Energy Resources Limited","url":"https://github.com/tc-openresilience-power/platform"},"license":{"name":"Code: MIT. Methodology and data: CC-BY 4.0.","url":"https://github.com/tc-openresilience-power/platform/blob/main/LICENSE"}},"servers":[{"url":"https://platform-lime-xi.vercel.app","description":"Live demo deployment (Vercel)"},{"url":"http://localhost:3000","description":"Local development"}],"tags":[{"name":"Facilities","description":"Facility registry and detail"},{"name":"Resilience","description":"Facility Resilience Index (FRI) scores"},{"name":"Ledger","description":"Child-impact ledger metrics"},{"name":"Dependencies","description":"Cross-sector dependency edges"},{"name":"Simulator","description":"Counterfactual deployment simulator"},{"name":"Triggers","description":"Anticipatory action trigger engine"},{"name":"Telemetry","description":"Synthetic facility power telemetry"},{"name":"Briefing","description":"AI Facility Briefing — rule-based v0"},{"name":"Assessments","description":"Field assessment submissions"},{"name":"Ranker","description":"Priority deployment ranker"},{"name":"Operations","description":"Health check and meta endpoints"}],"paths":{"/api/health":{"get":{"tags":["Operations"],"summary":"Service health check","description":"Returns build status, dataset counts, engine versions. Useful for uptime monitoring and CI smoke tests.","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/facilities":{"get":{"tags":["Facilities"],"summary":"List facilities","parameters":[{"$ref":"#/components/parameters/sector"},{"$ref":"#/components/parameters/admin_1"},{"$ref":"#/components/parameters/facility_type"}],"responses":{"200":{"description":"Facility collection","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"facilities":{"type":"array","items":{"$ref":"#/components/schemas/Facility"}}}}}}}}}},"/api/facilities/{id}":{"get":{"tags":["Facilities"],"summary":"Facility detail by ID","parameters":[{"$ref":"#/components/parameters/facilityId"}],"responses":{"200":{"description":"Facility","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Facility"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/fri":{"get":{"tags":["Resilience"],"summary":"FRI scores for every facility","description":"Returns the Facility Resilience Index score and band (low, moderate, high, critical) for every facility in the dataset.","responses":{"200":{"description":"FRI scores","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"scores":{"type":"array","items":{"$ref":"#/components/schemas/FRIScore"}}}}}}}}}},"/api/fri/{id}":{"get":{"tags":["Resilience"],"summary":"Detailed FRI breakdown for one facility","description":"Returns the four weighted sub-component scores (power, climate, water, AQ), the three multipliers (service criticality, children-at-risk, cross-sector amplifier), and the final FRI score plus band.","parameters":[{"$ref":"#/components/parameters/facilityId"}],"responses":{"200":{"description":"FRI breakdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FRIBreakdown"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/ledger/{id}":{"get":{"tags":["Ledger"],"summary":"Child-impact ledger for one facility","description":"Six per-facility monthly metrics: children served, service hours at risk, vaccine doses at risk, classroom hours lost, diesel litres, and CO2 tonnes.","parameters":[{"$ref":"#/components/parameters/facilityId"}],"responses":{"200":{"description":"Ledger metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerEntry"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/ledger/aggregate":{"get":{"tags":["Ledger"],"summary":"Aggregated ledger totals across all facilities","parameters":[{"$ref":"#/components/parameters/sector"},{"$ref":"#/components/parameters/admin_1"}],"responses":{"200":{"description":"Aggregated metrics","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/dependencies":{"get":{"tags":["Dependencies"],"summary":"Cross-sector dependency edges","parameters":[{"name":"edge_type","in":"query","schema":{"type":"string","enum":["water_from","patient_referral_to","shared_transformer_with","shared_grid_with","shared_borehole_with","shared_treatment_plant_with"]}},{"name":"facility","in":"query","schema":{"type":"string"},"description":"Filter to edges touching this facility ID"}],"responses":{"200":{"description":"Edge collection","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"dependencies":{"type":"array","items":{"$ref":"#/components/schemas/Dependency"}}}}}}}}}},"/api/simulator":{"get":{"tags":["Simulator"],"summary":"Run the counterfactual deployment simulator","description":"Given a budget, time horizon, prioritisation strategy, and optional scope filters, returns the selected interventions and projected child-impact deltas.","parameters":[{"name":"budget_usd","in":"query","required":true,"schema":{"type":"integer","minimum":1000,"maximum":10000000}},{"name":"horizon_months","in":"query","schema":{"type":"integer","enum":[3,6,12]}},{"name":"intervention","in":"query","schema":{"type":"string","enum":["smart_pick","solar_battery","cold_chain_retrofit","water_pump_backup","basic_battery_inverter"]}},{"name":"prioritisation","in":"query","schema":{"type":"string","enum":["top_fri","children_first","cross_sector_first","balanced"]}},{"$ref":"#/components/parameters/sector"},{"$ref":"#/components/parameters/admin_1"}],"responses":{"200":{"description":"Simulator output","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/triggers":{"get":{"tags":["Triggers"],"summary":"Evaluate all anticipatory-action trigger rules","description":"Runs every rule (CHILL-1, FLOOD-1, FUEL-1, AQ-1) against the seeded synthetic forecasts and returns fired events with severity, audit log, and rule rationale.","responses":{"200":{"description":"Trigger output","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/telemetry":{"get":{"tags":["Telemetry"],"summary":"List facilities with telemetry available","responses":{"200":{"description":"Telemetry index","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/telemetry/{id}":{"get":{"tags":["Telemetry"],"summary":"30-day synthetic telemetry series for one facility","parameters":[{"$ref":"#/components/parameters/facilityId"},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}}],"responses":{"200":{"description":"Telemetry series and anomalies","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/briefing/{id}":{"get":{"tags":["Briefing"],"summary":"AI Facility Briefing (rule-based v0)","description":"Returns a generated factual briefing for the facility. Every paragraph is cited; output is passed through advice-rewrite guardrails before return.","parameters":[{"$ref":"#/components/parameters/facilityId"}],"responses":{"200":{"description":"Briefing","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/assessments":{"post":{"tags":["Assessments"],"summary":"Submit a field assessment","description":"Accepts an offline-captured assessment payload from the PWA. v0 acknowledges receipt and returns an idempotent submission identifier; persistence to Postgres lands in the grant phase.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/ranker":{"get":{"tags":["Ranker"],"summary":"Priority deployment ranking","description":"Ranks facilities by (FRI reduction × children served) / cost. Tries every applicable intervention per facility and picks the best one unless an intervention is specified.","parameters":[{"name":"intervention","in":"query","schema":{"type":"string","enum":["best","solar_battery","cold_chain_retrofit","water_pump_backup","basic_battery_inverter"],"default":"best"}},{"$ref":"#/components/parameters/sector"},{"$ref":"#/components/parameters/admin_1"},{"$ref":"#/components/parameters/facility_type"},{"name":"top_n","in":"query","schema":{"type":"integer","minimum":1,"maximum":45,"default":10}}],"responses":{"200":{"description":"Ranked facility list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankerOutput"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"parameters":{"facilityId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Facility identifier (e.g. lag-h-001)"},"sector":{"name":"sector","in":"query","schema":{"type":"string","enum":["health","education","wash"]}},"admin_1":{"name":"admin_1","in":"query","schema":{"type":"string"},"description":"State (e.g. Lagos, Kano, Cross River)"},"facility_type":{"name":"facility_type","in":"query","schema":{"type":"string"}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"BadRequest":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}},"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"facility_count":{"type":"integer"},"ranker_version":{"type":"string"},"fri_version":{"type":"string"}}},"Facility":{"type":"object","properties":{"id":{"type":"string"},"name_pseudo":{"type":"string"},"sector":{"type":"string","enum":["health","education","wash"]},"facility_type":{"type":"string"},"admin_1":{"type":"string"},"admin_2":{"type":"string"},"geo":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"}}},"services":{"type":"array","items":{"type":"string"}},"population":{"type":"object","properties":{"children_served_estimated":{"type":"integer"},"monthly_users_estimated":{"type":"integer"}}}}},"FRIScore":{"type":"object","properties":{"facility_id":{"type":"string"},"fri":{"type":"number"},"band":{"type":"string","enum":["low","moderate","high","critical"]}}},"FRIBreakdown":{"type":"object","properties":{"facility_id":{"type":"string"},"components":{"type":"object","properties":{"power_vulnerability":{"type":"number"},"climate_exposure":{"type":"number"},"water_continuity":{"type":"number"},"air_quality_burden":{"type":"number"}}},"weighted_base":{"type":"number"},"multipliers":{"type":"object","properties":{"service_criticality":{"type":"number"},"children_at_risk":{"type":"number"},"cross_sector_dependency_amplifier":{"type":"number"}}},"fri":{"type":"number"},"band":{"type":"string","enum":["low","moderate","high","critical"]}}},"LedgerEntry":{"type":"object","properties":{"facility_id":{"type":"string"},"children_served_monthly":{"type":"number"},"service_hours_at_risk_monthly":{"type":"number"},"vaccine_doses_at_risk_monthly":{"type":"number"},"classroom_hours_lost_monthly":{"type":"number"},"diesel_litres_monthly":{"type":"number"},"co2_tonnes_monthly":{"type":"number"}}},"Dependency":{"type":"object","properties":{"id":{"type":"string"},"from_facility":{"type":"string"},"to_facility":{"type":"string"},"edge_type":{"type":"string"},"notes":{"type":"string"}}},"RankerOutput":{"type":"object","properties":{"ranker_version":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"facility_count":{"type":"integer"},"top_n":{"type":"integer"},"total_cost_for_top_n_usd":{"type":"number"},"ranked":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"facility_id":{"type":"string"},"facility_name":{"type":"string"},"sector":{"type":"string"},"admin_1":{"type":"string"},"best_intervention":{"type":"string"},"best_intervention_name":{"type":"string"},"cost_usd":{"type":"number"},"fri_before":{"type":"number"},"fri_after":{"type":"number"},"fri_reduction":{"type":"number"},"band_before":{"type":"string"},"band_after":{"type":"string"},"children_served_estimated":{"type":"integer"},"priority_score":{"type":"number"},"cumulative_cost_usd":{"type":"number"}}}},"notes":{"type":"array","items":{"type":"string"}}}}}}}