{"openapi":"3.1.0","info":{"title":"Ericeira Review public discovery API","version":"1.0.0","description":"Read-only contract for agents and crawlers that need to discover approved Ericeira Review listings and first-party reviews. Mutating endpoints are intentionally omitted."},"servers":[{"url":"https://ericeirareview.com/api/v1","description":"production"},{"url":"http://localhost:3000/api/v1","description":"local dev"}],"components":{"schemas":{"Listing":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"bucket":{"type":"string","enum":["spots","people","community","events"]},"name":{"type":"string"},"slug":{"type":"string"},"short_description":{"type":"string","nullable":true},"long_description":{"type":"string","nullable":true},"hero_image_url":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"instagram":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"city":{"type":"string"},"country":{"type":"string"},"lat":{"type":"number","nullable":true},"lng":{"type":"number","nullable":true},"category":{"type":"string","nullable":true},"price_range":{"type":"string","nullable":true},"gallery_images":{"type":"array","items":{"type":"string"},"nullable":true},"is_featured":{"type":"boolean"},"is_claimed":{"type":"boolean"},"is_verified":{"type":"boolean"},"review_count":{"type":"integer"},"avg_rating":{"type":"number"},"updated_at":{"type":"string","format":"date-time"}}},"Review":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"listing_id":{"type":"string","format":"uuid"},"display_name":{"type":"string"},"title":{"type":"string","nullable":true},"rating":{"type":"integer","minimum":1,"maximum":5},"body":{"type":"string"},"recommendation":{"type":"string","enum":["yes","maybe","no"],"nullable":true},"useful_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/listings":{"get":{"tags":["Listings"],"summary":"List approved listings","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"bucket","in":"query","schema":{"type":"string","enum":["spots","people","community","events"]}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"town","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search name and short description"},{"name":"claimed","in":"query","schema":{"type":"string","enum":["true"]}},{"name":"verified","in":"query","schema":{"type":"string","enum":["true"]}},{"name":"featured","in":"query","schema":{"type":"string","enum":["true"]}}],"responses":{"200":{"description":"Paginated approved listings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"meta":{"type":"object","properties":{"total":{"type":"integer","nullable":true},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}}}}},"/listings/{bucket}/{slug}":{"parameters":[{"name":"bucket","in":"path","required":true,"schema":{"type":"string","enum":["spots","people","community","events"]}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Listings"],"summary":"Get one listing by bucket and slug","responses":{"200":{"description":"Listing detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"404":{"description":"Listing not found"}}}},"/listings/{bucket}/{slug}/reviews":{"parameters":[{"name":"bucket","in":"path","required":true,"schema":{"type":"string","enum":["spots","people","community","events"]}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Reviews"],"summary":"List approved reviews for a listing","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Paginated approved reviews","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Review"}},"meta":{"type":"object","properties":{"total":{"type":"integer","nullable":true},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}}}}},"/reviews":{"get":{"tags":["Reviews"],"summary":"List all approved public reviews","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"bucket","in":"query","schema":{"type":"string","enum":["spots","people","community","events"]}},{"name":"rating","in":"query","schema":{"type":"integer","minimum":1,"maximum":5}},{"name":"listing_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Paginated approved reviews across approved listings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Review"}},"meta":{"type":"object","properties":{"total":{"type":"integer","nullable":true},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}}}}}}}