{"openapi":"3.1.0","info":{"title":"Staylist API","version":"0.1.0","description":"Honest hotel ratings and tracked booking links. Free, no authentication. Rate limit: 30 req/min, 400 req/day per IP. The same data is available over MCP at /mcp."},"servers":[{"url":"https://staylist.world"}],"paths":{"/api/hotels/search":{"get":{"operationId":"searchHotels","summary":"Search hotels by city or natural-language query","parameters":[{"in":"query","required":false,"name":"city","schema":{"type":"string"},"description":"City name, e.g. Lisbon"},{"in":"query","required":false,"name":"country_code","schema":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166-1 alpha-2"},{"in":"query","required":false,"name":"query","schema":{"type":"string"},"description":"Natural-language search"},{"in":"query","required":false,"name":"checkin","schema":{"type":"string","format":"date"}},{"in":"query","required":false,"name":"checkout","schema":{"type":"string","format":"date"}},{"in":"query","required":false,"name":"adults","schema":{"type":"integer","default":2}},{"in":"query","required":false,"name":"children_ages","schema":{"type":"string"},"description":"Comma-separated ages, e.g. 4,7"},{"in":"query","required":false,"name":"min_rating","schema":{"type":"number","minimum":0,"maximum":10}},{"in":"query","required":false,"name":"max_price_per_night","schema":{"type":"number"}},{"in":"query","required":false,"name":"stars","schema":{"type":"string"},"description":"Comma-separated, e.g. 4,5"},{"in":"query","required":false,"name":"limit","schema":{"type":"integer","default":10,"maximum":20}}],"responses":{"200":{"description":"Matching hotels with booking links","content":{"application/json":{"schema":{"type":"object","properties":{"hotels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"rating":{"type":"number","description":"Guest rating 0-10"},"stars":{"type":"integer"},"review_count":{"type":"integer"},"price_per_night":{"type":"number"},"currency":{"type":"string"},"pros":{"type":"array","items":{"type":"string"}},"cons":{"type":"array","items":{"type":"string"}},"photo":{"type":"string"},"url":{"type":"string"},"booking_links":{"type":"array","items":{"type":"object","properties":{"site":{"type":"string"},"url":{"type":"string"},"primary":{"type":"boolean"},"note":{"type":"string"}}}}}}},"provider":{"type":"string"},"note":{"type":"string"}}}}}},"400":{"description":"Invalid parameters"},"429":{"description":"Rate limited"}}}},"/api/hotels/{id}":{"get":{"operationId":"getHotel","summary":"Full detail for one hotel, optionally with rates","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"checkin","in":"query","schema":{"type":"string","format":"date"}},{"name":"checkout","in":"query","schema":{"type":"string","format":"date"}},{"name":"adults","in":"query","schema":{"type":"integer"}},{"name":"children_ages","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Hotel detail","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"city":{"type":"string"},"country":{"type":"string"},"rating":{"type":"number","description":"Guest rating 0-10"},"stars":{"type":"integer"},"review_count":{"type":"integer"},"price_per_night":{"type":"number"},"currency":{"type":"string"},"pros":{"type":"array","items":{"type":"string"}},"cons":{"type":"array","items":{"type":"string"}},"photo":{"type":"string"},"url":{"type":"string"},"booking_links":{"type":"array","items":{"type":"object","properties":{"site":{"type":"string"},"url":{"type":"string"},"primary":{"type":"boolean"},"note":{"type":"string"}}}}}}}}},"400":{"description":"Invalid parameters or unknown hotel"},"429":{"description":"Rate limited"}}}},"/api/hotels/{id}/booking-links":{"get":{"operationId":"getBookingLinks","summary":"Tracked booking links for a hotel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"checkin","in":"query","schema":{"type":"string","format":"date"}},{"name":"checkout","in":"query","schema":{"type":"string","format":"date"}},{"name":"adults","in":"query","schema":{"type":"integer"}},{"name":"children_ages","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Booking links, primary first","content":{"application/json":{"schema":{"type":"object","properties":{"hotel_name":{"type":"string"},"links":{"type":"array","items":{"type":"object","properties":{"site":{"type":"string"},"url":{"type":"string"},"primary":{"type":"boolean"},"note":{"type":"string"}}}},"instructions":{"type":"string"}}}}}},"400":{"description":"Unknown hotel"},"429":{"description":"Rate limited"}}}},"/api/destinations":{"get":{"operationId":"listDestinations","summary":"Covered destinations","responses":{"200":{"description":"Destination list","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"destinations":{"type":"array","items":{"type":"object","properties":{"city":{"type":"string"},"country":{"type":"string"},"countryCode":{"type":"string"},"hotels":{"type":"integer"}}}}}}}}},"429":{"description":"Rate limited"}}}},"/api/docs":{"get":{"operationId":"apiDocs","summary":"Machine-readable service description","responses":{"200":{"description":"Service documentation"}}}}}}