{"openapi":"3.1.0","info":{"title":"Overwater World API","version":"1","description":"Every overwater villa and bungalow resort in the world, room type by room type."},"servers":[{"url":"https://overwaterworld.com"}],"paths":{"/api/v1/health":{"get":{"summary":"Liveness","responses":{"200":{"description":"ok"}}}},"/api/v1/search":{"get":{"summary":"Search published entities by name","parameters":[{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"list envelope"}}}},"/api/v1/compare":{"get":{"summary":"Canonical compare url for a set of slugs","parameters":[{"name":"ids","in":"query","required":true,"description":"A comma-separated list of resort slugs or qualified room-type keys (<resort-slug>~<room-slug>)","schema":{"type":"string"}}],"responses":{"200":{"description":"compare"}}}},"/api/v1/inquiries":{"post":{"summary":"Create an inquiry (lead) for a published entity","description":"Creates a lead and runs delivery to the operator by email and webhook in the same request; the response reports each delivery channel's status.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entity","email","dates","party","budget","must_haves"],"properties":{"entity":{"type":"string","description":"A published resort slug, or a room type as <resort-slug>~<room-slug>"},"email":{"type":"string","format":"email"},"dates":{"type":"object","required":["check_in","check_out"],"properties":{"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date","description":"After check_in"}}},"party":{"type":"object","required":["adults","children"],"properties":{"adults":{"type":"integer","minimum":1,"maximum":12},"children":{"type":"integer","minimum":0,"maximum":12}}},"budget":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","minimum":0,"description":"Minor units"},"currency":{"type":"string","minLength":3,"maxLength":3}}},"must_haves":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":60}},"message":{"type":"string","maxLength":1000}}},"example":{"entity":"lagoon-reef-maldives","email":"traveler@example.com","dates":{"check_in":"2026-11-01","check_out":"2026-11-05"},"party":{"adults":2,"children":0},"budget":{"amount":90000,"currency":"USD"},"must_haves":["glass floor"],"message":"Anniversary trip."}}}},"responses":{"201":{"description":"Lead created; delivery channel statuses returned"},"400":{"description":"validation_failed"},"404":{"description":"not_found — unknown or unpublished entity"},"409":{"description":"ambiguous_slug — a bare room-type slug shared by more than one resort; detail lists the candidate resort slugs"},"429":{"description":"rate_limited — too many inquiries from this connection"}}}},"/api/v1/subscribers":{"post":{"summary":"Subscribe an email address to a site's updates","description":"Creates a pending subscriber and sends one double opt-in confirmation mail with a signed link; the address joins the list only once that confirmation link is opened.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","source_path"],"properties":{"email":{"type":"string","format":"email"},"source_path":{"type":"string","minLength":1,"maxLength":512,"description":"The path the subscriber came from"},"entity":{"type":"string","description":"A published resort or room-type slug, when known"}}},"example":{"email":"traveler@example.com","source_path":"/resorts/lagoon-reef-maldives","entity":"lagoon-reef-maldives"}}}},"responses":{"201":{"description":"Subscriber created pending; confirmation mail delivery reported"},"400":{"description":"validation_failed"},"429":{"description":"rate_limited — too many subscriptions from this connection"}}}},"/go/{offerId}":{"get":{"summary":"Record a click and redirect to the offer's booking page","parameters":[{"name":"offerId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the resort's booking page"},"404":{"description":"not_found — unknown or inactive offer"}}}},"/api/v1/destinations":{"get":{"summary":"List published destinations","parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"list envelope"}}}},"/api/v1/destinations/{slug}":{"get":{"summary":"One destination","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"destination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/destination"}}}},"404":{"description":"not found"}}}},"/api/v1/brands":{"get":{"summary":"List published brands","parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"list envelope"}}}},"/api/v1/brands/{slug}":{"get":{"summary":"One brand","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/brand"}}}},"404":{"description":"not found"}}}},"/api/v1/resorts":{"get":{"summary":"List published resorts","parameters":[{"name":"island_transfer","in":"query","schema":{"type":"string"}},{"name":"house_reef","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"list envelope"}}}},"/api/v1/resorts/{slug}":{"get":{"summary":"One resort","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"destination","in":"query","schema":{"type":"string"},"description":"The slug of the resort's destination; required when more than one destination has a resort with this slug"}],"responses":{"200":{"description":"resort","content":{"application/json":{"schema":{"$ref":"#/components/schemas/resort"}}}},"404":{"description":"not found"},"409":{"description":"ambiguous_slug — more than one destination has a resort with this slug; detail lists the candidate destination slugs"}}}},"/api/v1/room-types":{"get":{"summary":"List published room-types","parameters":[{"name":"orientation","in":"query","schema":{"type":"string"}},{"name":"glass_floor","in":"query","schema":{"type":"string"}},{"name":"private_pool","in":"query","schema":{"type":"string"}},{"name":"direct_lagoon_access","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"list envelope"}}}},"/api/v1/room-types/{slug}":{"get":{"summary":"One room_type","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"resort","in":"query","schema":{"type":"string"},"description":"The slug of the room_type's resort; required when more than one resort has a room_type with this slug"}],"responses":{"200":{"description":"room_type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/room_type"}}}},"404":{"description":"not found"},"409":{"description":"ambiguous_slug — more than one resort has a room_type with this slug; detail lists the candidate resort slugs"}}}},"/api/v1/lists/glass-floor-villas":{"get":{"summary":"Overwater villas with glass floors","description":"Room types whose floor includes a glass panel, ranked by water depth and then by size.","responses":{"200":{"description":"list envelope"}}}},"/api/v1/lists/overwater-villas-with-private-pool":{"get":{"summary":"Overwater villas with a private pool","description":"Room types with a private pool, ranked by size and then by how many guests they sleep.","responses":{"200":{"description":"list envelope"}}}},"/api/v1/lists/points-bookable-overwater":{"get":{"summary":"Overwater villas you can book with points","description":"Room types a hotel loyalty program can book on points, ranked by size.","responses":{"200":{"description":"list envelope"}}}}},"components":{"schemas":{"destination":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"attrs":{"type":"object","properties":{"country_code":{"type":"string","description":"Country"},"region":{"type":"string","description":"Region"},"airport_code":{"type":"string","description":"Airport"},"time_zone":{"type":"string","description":"Time zone"},"currency":{"type":"string","description":"Currency"},"season_windows":{"type":"array","description":"Season windows"},"access_note":{"type":"string","description":"Getting there"},"typical_transfer":{"type":"string","description":"Typical transfer","enum":["speedboat","seaplane","domestic_flight_and_boat","road"]},"visa_note":{"type":"string","description":"Visa"},"weather_risk_window":{"type":"string","description":"Cyclone or monsoon window"},"description_url":{"type":"string","description":"Tourism board page"}}}}},"brand":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"attrs":{"type":"object","properties":{"official_website":{"type":"string","description":"Official website"},"loyalty_program":{"type":"string","description":"Loyalty program","enum":["Marriott Bonvoy","Hilton Honors","World of Hyatt","IHG One Rewards","Accor ALL","none"]},"parent_company":{"type":"string","description":"Parent company"}}}}},"resort":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"attrs":{"type":"object","properties":{"official_website":{"type":"string","description":"Official website"},"booking_url":{"type":"string","description":"Booking page"},"phone":{"type":"string","description":"Phone"},"address":{"type":"string","description":"Address"},"position":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}},"required":["lat","lng"],"description":"Position"},"star_rating":{"type":"number","description":"Star rating"},"check_in":{"type":"string","description":"Check-in"},"check_out":{"type":"string","description":"Check-out"},"currency":{"type":"string","description":"Currency"},"rate_from":{"type":"number","description":"Rate from"},"images":{"type":"array","description":"Images"},"amenities":{"type":"array","description":"Amenities"},"summary":{"type":"string","description":"Summary"},"adults_only":{"type":"boolean","description":"Adults only"},"all_inclusive":{"type":"boolean","description":"All inclusive"},"google_place_id":{"type":"string","description":"Google place"},"total_overwater_units":{"type":"integer","description":"Overwater units"},"island_transfer":{"type":"string","description":"Island transfer","enum":["speedboat","seaplane","domestic_flight_and_boat"]},"transfer_time_min":{"type":"integer","description":"Transfer time (min)"},"lagoon_type":{"type":"string","description":"Lagoon","enum":["enclosed","open","reef_edge"]},"house_reef":{"type":"boolean","description":"House reef"},"kids_policy":{"type":"string","description":"Kids policy"}}}}},"room_type":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"attrs":{"type":"object","properties":{"size_sqm":{"type":"number","description":"Size (m²)"},"max_occupancy":{"type":"integer","description":"Max occupancy"},"bedrooms":{"type":"integer","description":"Bedrooms"},"bed_config":{"type":"string","description":"Beds"},"view":{"type":"string","description":"View"},"private_pool":{"type":"boolean","description":"Private pool"},"rate_from":{"type":"number","description":"Rate from"},"images":{"type":"array","description":"Images"},"orientation":{"type":"string","description":"Orientation","enum":["sunrise","sunset","lagoon","ocean","mixed"]},"glass_floor":{"type":"boolean","description":"Glass floor"},"direct_lagoon_access":{"type":"boolean","description":"Direct lagoon access"},"water_depth_m":{"type":"number","description":"Water depth (m)"},"distance_from_main_island_m":{"type":"number","description":"Distance from main island (m)"},"over_water_fraction":{"type":"string","description":"Over-water footprint","enum":["full","partial"]},"points_bookable":{"type":"array","description":"Points bookability"}}}}}}}}