{"openapi":"3.1.0","info":{"title":"Airva Cooling Planner API","version":"2.0","summary":"How to heat, cool and run hot water for a UK home, from a few structured answers.","description":"A deterministic recommendation engine with two routes. Cooling some rooms: portable, window, through-wall (monobloc), single-split, multi-split or ducted, with indicative costs in GBP. A whole home: nine complete architectures that each assign heating, cooling and hot water to equipment and say what happens to the radiators, with a qualitative cost tier (no whole-home price is published), the grant position, and what an installer must confirm. Both carry the reasons, the alternatives, and which single change would alter the verdict. Two shapes are valid. A COOLING request omits `home` and carries `rooms` with scope \"one_room\" or \"few_rooms\"; it returns a system for those rooms. A WHOLE-HOME request carries a `home` block with scope \"whole_home\" and `rooms: []`; it returns a plan that assigns heating, cooling and hot water. A payload mixing the two is rejected with 400. No personal data in or out. Free; rate-limited per IP. Responses carry a disclaimer that must be shown to end users: it is an initial guide, not a system design or a quotation.","termsOfService":"https://www.airva.co.uk/developers#terms","contact":{"name":"Airva","url":"https://www.airva.co.uk/contact"}},"servers":[{"url":"https://www.airva.co.uk"}],"paths":{"/api/recommend":{"post":{"operationId":"recommend","summary":"Recommend a heating, cooling and hot-water plan for a home","requestBody":{"required":true,"description":"Two shapes are valid. A COOLING request omits `home` and carries `rooms` with scope \"one_room\" or \"few_rooms\"; it returns a system for those rooms. A WHOLE-HOME request carries a `home` block with scope \"whole_home\" and `rooms: []`; it returns a plan that assigns heating, cooling and hot water. A payload mixing the two is rejected with 400.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answers"}}}},"responses":{"200":{"description":"The recommendation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recommendation"}}}},"400":{"description":"The answers did not validate. `issues` lists each problem."},"429":{"description":"Rate limit exceeded. Try again later."}}}},"/api/recommend/questions":{"get":{"operationId":"listQuestions","summary":"The questions the planner asks, with their options and plain-English copy","responses":{"200":{"description":"Questions, options, and the JSON Schema for Answers."}}}}},"components":{"schemas":{"Answers":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"scope":{"type":"string","enum":["one_room","few_rooms","whole_home"]},"rooms":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["bedroom","living_room","kitchen_open_plan","home_office","loft","conservatory","other"]},"sizeBand":{"type":"string","enum":["small","medium","large","very_large","unknown"]}},"required":["type","sizeBand"],"additionalProperties":false}},"permanentChanges":{"type":"string","enum":["yes","permission","no","unknown"]},"outdoorUnit":{"type":"string","enum":["yes","probably","no","unknown"]},"windowType":{"type":"string","enum":["vertical_sash","sliding","casement","tilt_turn","other","unknown"]},"usage":{"type":"string","enum":["occasional","summer","frequent","unknown"]},"heating":{"type":"string","enum":["yes","nice_to_have","no"]},"installPreference":{"type":"string","enum":["fixed","removable","either"]},"priority":{"type":"string","enum":["overall","quiet","upfront_cost","running_cost","minimal_work","external_appearance"]},"secondaryPriority":{"type":"string","enum":["overall","quiet","upfront_cost","running_cost","minimal_work","external_appearance"]},"costStance":{"type":"string","enum":["under_500","under_1500","open_to_fixed","unknown"]},"extras":{"maxItems":5,"type":"array","items":{"type":"string","enum":["clean_air","humidity","quiet_night","app_control","discreet"]}},"wholeHome":{"type":"object","properties":{"replaceHeating":{"type":"string","enum":["yes","no","unsure"]},"majorBuildingWork":{"type":"string","enum":["yes","no","maybe"]}},"required":["replaceHeating","majorBuildingWork"],"additionalProperties":false},"home":{"type":"object","properties":{"objective":{"type":"string","enum":["comfort","heating_replacement","renovation","unsure"]},"existingHeating":{"type":"string","enum":["gas_boiler","oil_boiler","lpg_boiler","electric_radiators","storage_heaters","air_to_water","air_to_air","communal","none","other","unknown"]},"heatDistribution":{"type":"string","enum":["radiators","underfloor","mixture","electric_panels","storage","wall_units","warm_air","unknown"]},"hotWater":{"type":"string","enum":["combi","boiler_cylinder","immersion_cylinder","heat_pump_cylinder","communal","instant_electric","other","unknown"]},"retain":{"type":"string","enum":["keep_heating_add_cooling","keep_radiators_replace_boiler","keep_hot_water","replace_everything","show_trade_offs"]},"coverage":{"maxItems":6,"type":"array","items":{"type":"string","enum":["living_areas","bedrooms","kitchen_open_plan","loft_top_floor","conservatory","whole_home","none"]}},"propertyType":{"type":"string","enum":["detached","semi_detached","terraced","bungalow","flat_purpose_built","flat_converted","other"]},"bedrooms":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3},{"type":"number","const":4},{"type":"number","const":5}]},"storeys":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]},"disruption":{"type":"string","enum":["minimal","some","renovating","major","unknown"]},"appearance":{"type":"string","enum":["visible_fine","pay_for_discreet","concealed_only","unknown"]},"concealedSpace":{"type":"string","enum":["loft","ceiling_void","being_created","none","unknown"]},"outdoorLocation":{"maxItems":7,"type":"array","items":{"type":"string","enum":["ground_beside_house","side_passage","external_wall","balcony_terrace","flat_roof","garden_patio","nowhere","unknown"]}},"outdoorSensitivity":{"type":"string","enum":["not_particularly","one_not_several","hidden_as_possible","planning_restrictions","unknown"]},"permanentChanges":{"type":"string","enum":["yes","permission","no","unknown"]},"constraints":{"maxItems":5,"type":"array","items":{"type":"string","enum":["listed_or_conservation","leasehold_flat","rented","tight_cylinder_space","no_loft_access"]}},"budget":{"type":"string","enum":["lowest_disruption","modest","mid","premium","show_realistic"]},"grantCheck":{"type":"object","properties":{"nation":{"type":"string","enum":["england","wales","scotland","northern_ireland","unknown"]},"ownership":{"type":"string","enum":["owner_occupier","landlord","leaseholder","tenant","other","unknown"]},"newBuild":{"anyOf":[{"type":"boolean"},{"type":"string","const":"unknown"}]}},"required":["nation","ownership","newBuild"],"additionalProperties":false},"weighBy":{"type":"string","enum":["overall","lowest_disruption","lowest_upfront_cost","lowest_running_cost","best_cooling","most_discreet","best_complete_replacement"]}},"required":["objective","existingHeating","hotWater","coverage","propertyType","bedrooms","disruption","appearance","outdoorLocation","permanentChanges","budget"],"additionalProperties":false}},"required":["scope","rooms","permanentChanges","outdoorUnit","priority"],"additionalProperties":false},"Cost":{"type":"object","properties":{"low":{"type":"integer"},"high":{"type":"integer"},"currency":{"const":"GBP"},"kind":{"enum":["purchase","installed"]},"basis":{"type":"string"}},"required":["low","high","currency","kind","basis"]},"Recommendation":{"type":"object","properties":{"engineVersion":{"type":"string"},"input":{"$ref":"#/components/schemas/Answers"},"mode":{"enum":["single_room","multi_room","whole_home"]},"summary":{"type":"string","description":"One sentence: the verdict and why."},"primary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"subtitle":{"type":"string"},"guideUrl":{"type":"string","format":"uri"},"cost":{"$ref":"#/components/schemas/Cost"},"reasons":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"text":{"type":"string"}}}}}},"confidence":{"type":"object","properties":{"level":{"enum":["high","medium","low"]},"reason":{"type":"string"}}},"alternatives":{"type":"array","items":{"type":"object"}},"ruledOut":{"type":"array","items":{"type":"object"}},"checksRequired":{"type":"array","items":{"type":"object"}},"notes":{"type":"array","items":{"type":"object"}},"suitsBestAboveBudget":{"type":"object","description":"Present when a stated budget kept a better-suited system off the top."},"whatWouldChange":{"type":"array","description":"Single answer changes that would alter the verdict, each with the resulting system and cost.","items":{"type":"object"}},"links":{"type":"object","properties":{"plan":{"type":"string","format":"uri"},"planner":{"type":"string","format":"uri"},"getMatched":{"type":"string","format":"uri"},"commonSituations":{"type":"string","format":"uri"}}},"disclaimer":{"type":"string"}},"required":["engineVersion","input","mode","summary","primary","confidence","alternatives","ruledOut","checksRequired","notes","whatWouldChange","links","disclaimer"]}}}}