{"openapi":"3.1.0","info":{"title":"Yenta Destination Read API","version":"1.0.0","description":"This destination's machine-consumable JSON reads over `/v1/public/destination`: overview, facets, listings, events, offers, seasonality, guides and FAQs. Anonymous, read-only, no authentication. Every result carries a `source` freshness reference. Powered by Yenta."},"servers":[{"url":"https://loscabos.venues.dev.yentaknows.ai","description":"This destination host."}],"externalDocs":{"description":"llms.txt — the agent entrypoint naming every Yenta surface.","url":"https://dev.yentaknows.ai/llms.txt"},"x-mcp":{"url":"https://loscabos.venues.dev.yentaknows.ai/mcp","transport":"streamable-http"},"paths":{"/v1/public/destination/overview":{"get":{"operationId":"get_destination_overview","summary":"Get this destination's overview","description":"What the destination offers and what's on in one call: counts by category, currency, timezone and a preview of a few places (catalogue order, not a ranking) and the next events.","responses":{"200":{"description":"The destination overview (counts by category, event_count, guide_topics, faq_count, offer_count, and preview: the first few listings and upcoming events, as the default listings/events pages order them, and complete: whether nothing more exists), or not_available; if preview.complete is true, no follow-up call is needed.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","not_available"]},"reason":{"type":"string"},"item":{"$ref":"#/components/schemas/Content"},"source":{"$ref":"#/components/schemas/Source"}},"required":["status","source"]}}}},"404":{"description":"Wrong host family, or no such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/destination/facets":{"get":{"operationId":"list_destination_facets","summary":"List this destination's facets","description":"The valid area, category and tag filter values for the search reads.","parameters":[{"name":"kind","in":"query","required":false,"description":"Return only this facet family; omit for all three.","schema":{"type":"string","enum":["area","category","tag"]}}],"responses":{"200":{"description":"The facet vocabulary, or not_available.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","not_available"]},"reason":{"type":"string"},"item":{"$ref":"#/components/schemas/Content"},"source":{"$ref":"#/components/schemas/Source"}},"required":["status","source"]}}}},"404":{"description":"Wrong host family, or no such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A parameter fell outside its bounds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/destination/listings":{"get":{"operationId":"search_listings","summary":"Search this destination's listings","description":"Listings by text, category, area and tags; optionally near a listing.","parameters":[{"name":"query","in":"query","required":false,"description":"Text to match against listing names and descriptions.","schema":{"type":"string","maxLength":256}},{"name":"category","in":"query","required":false,"description":"Category name or slug from /v1/public/destination/facets.","schema":{"type":"string"}},{"name":"area","in":"query","required":false,"description":"Area name or slug from /v1/public/destination/facets.","schema":{"type":"string"}},{"name":"tags","in":"query","required":false,"description":"Tag slugs; only listings carrying ALL are returned.","schema":{"type":"array","items":{"type":"string"},"maxItems":8}},{"name":"language","in":"query","required":false,"description":"Language code (e.g. 'en', 'es'); defaults to the destination's.","schema":{"type":"string"}},{"name":"near_listing_id","in":"query","required":false,"description":"A listing id (or a fetch id 'listing:<destination>:<id>'); returns listings within radius_km, nearest first.","schema":{"type":"string"}},{"name":"radius_km","in":"query","required":false,"description":"Search radius in km around near_listing_id.","schema":{"type":"number","minimum":0,"maximum":50.0}},{"name":"limit","in":"query","required":false,"description":"Maximum items to return.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Offset of the first item to return.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"A page of listing summaries {id, name, description_snippet, category, area, locality, price_band, tags, canonical_url}, empty fields omitted; get_listing has the full detail and description.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","not_available"]},"reason":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Content"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"source":{"$ref":"#/components/schemas/Source"}},"required":["status","source"]}}}},"404":{"description":"Wrong host family, or no such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A parameter fell outside its bounds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/destination/listings/{listing_id}":{"get":{"operationId":"get_listing","summary":"Get one listing","description":"One listing's full detail by its id, or `not_available`.","parameters":[{"name":"listing_id","in":"path","required":true,"description":"The listing's id, as returned by the listing search (a fetch id 'listing:<destination>:<id>' also resolves).","schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"The listing detail, or not_available.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","not_available"]},"reason":{"type":"string"},"item":{"$ref":"#/components/schemas/Content"},"source":{"$ref":"#/components/schemas/Source"}},"required":["status","source"]}}}},"404":{"description":"Wrong host family, or no such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A parameter fell outside its bounds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/destination/events":{"get":{"operationId":"search_events","summary":"Search this destination's events","description":"Events overlapping [from_date, to_date] (defaults to from today), optionally matching every query word.","parameters":[{"name":"query","in":"query","required":false,"description":"Words matched in any order against event names and descriptions.","schema":{"type":"string","maxLength":256}},{"name":"from_date","in":"query","required":false,"description":"ISO date; defaults to today.","schema":{"type":"string","format":"date"}},{"name":"to_date","in":"query","required":false,"description":"ISO date; open-ended if omitted.","schema":{"type":"string","format":"date"}},{"name":"category","in":"query","required":false,"description":"Category name or slug from /v1/public/destination/facets.","schema":{"type":"string"}},{"name":"area","in":"query","required":false,"description":"Area name or slug from /v1/public/destination/facets.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum items to return.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Offset of the first item to return.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"A page of events, each with a description_snippet; the full description is on the destination's /events page and at canonical_url. Results carry booking_url, the partner's booking page when present, and canonical_url, the destination's page.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","not_available"]},"reason":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Content"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"source":{"$ref":"#/components/schemas/Source"}},"required":["status","source"]}}}},"404":{"description":"Wrong host family, or no such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A parameter fell outside its bounds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/destination/offers":{"get":{"operationId":"search_offers","summary":"Search this destination's offers","description":"Offers valid on a date (defaults to today; expired offers are dropped).","parameters":[{"name":"valid_on","in":"query","required":false,"description":"ISO date an offer must be valid on (valid_from to valid_through, inclusive); defaults to today.","schema":{"type":"string","format":"date"}},{"name":"category","in":"query","required":false,"description":"Category name or slug from /v1/public/destination/facets.","schema":{"type":"string"}},{"name":"area","in":"query","required":false,"description":"Area name or slug from /v1/public/destination/facets.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum items to return.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Offset of the first item to return.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"A page of offers, each with a description_snippet; the full description is on the destination's /offers page and at canonical_url. Results carry booking_url, the partner's booking page when present, and canonical_url, the destination's page.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","not_available"]},"reason":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Content"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"source":{"$ref":"#/components/schemas/Source"}},"required":["status","source"]}}}},"404":{"description":"Wrong host family, or no such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A parameter fell outside its bounds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/destination/seasonality":{"get":{"operationId":"get_seasonality","summary":"Get this destination's seasonality","description":"Per-month climate and highlights; all twelve, or one, optionally filtered by interest.","parameters":[{"name":"month","in":"query","required":false,"description":"Month 1-12; omit for all twelve.","schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"interest","in":"query","required":false,"description":"An activity or season, e.g. whales; keeps the months whose highlights or notes mention it.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The month(s), or not_available.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","not_available"]},"reason":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Content"}},"source":{"$ref":"#/components/schemas/Source"}},"required":["status","source"]}}}},"404":{"description":"Wrong host family, or no such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A parameter fell outside its bounds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/destination/guides":{"get":{"operationId":"get_guide","summary":"Read this destination's guides","description":"Editorial guide entries, filtered by topic and/or text, a few per page; item.titles lists every match.","parameters":[{"name":"topic","in":"query","required":false,"description":"Guide topic; omit for all.","schema":{"type":"string","enum":["weather","getting_here","transportation","entry_requirements","emergencies","safety","culture","packing","sustainability"]}},{"name":"query","in":"query","required":false,"description":"Text to match in the guide title or body.","schema":{"type":"string","maxLength":256}},{"name":"limit","in":"query","required":false,"description":"Entries per page; omit for the server's short default.","schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"cursor","in":"query","required":false,"description":"Offset of the first item to return.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"A page of guides plus the titles index, or not_available; pass pagination.next_cursor as cursor for the next page.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","not_available"]},"reason":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Content"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"source":{"$ref":"#/components/schemas/Source"},"item":{"type":"object","description":"titles: every matched entry's topic and title, so page one indexes the rest.","properties":{"titles":{"type":"array","items":{"type":"object","properties":{"topic":{"type":"string"},"title":{"type":"string"}}}}}}},"required":["status","source"]}}}},"404":{"description":"Wrong host family, or no such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A parameter fell outside its bounds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/destination/faq":{"get":{"operationId":"get_faq","summary":"Search this destination's FAQs","description":"This destination's FAQs, optionally filtered by text.","parameters":[{"name":"query","in":"query","required":false,"description":"Text to match in the question or answer.","schema":{"type":"string","maxLength":256}},{"name":"limit","in":"query","required":false,"description":"Maximum items to return.","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},{"name":"cursor","in":"query","required":false,"description":"Offset of the first item to return.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"A page of FAQs.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","not_available"]},"reason":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Content"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"source":{"$ref":"#/components/schemas/Source"}},"required":["status","source"]}}}},"404":{"description":"Wrong host family, or no such resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A parameter fell outside its bounds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Source":{"type":"object","description":"Which approved revision an answer was read from.","properties":{"content_version":{"type":"integer"},"source":{"type":"string","description":"'directory' for cross-venue reads, or 'approved-content-revision:<id>' for a single venue/destination."},"approved_at":{"type":"string","format":"date-time","description":"When the cited revision was approved (ISO-8601), so an answer can be quoted 'as of' that time. Present on a single venue/destination answer and on each search_venues candidate's own per-item source; absent on a cross-venue directory footer."},"powered_by":{"type":"string","description":"Brand signature on the entry reads only."}},"required":["content_version","source"]},"Pagination":{"type":"object","description":"The page actually served; next_cursor is null past the last page.","properties":{"limit":{"type":"integer"},"cursor":{"type":"integer"},"next_cursor":{"type":["integer","null"]},"total":{"type":"integer"}},"required":["limit","cursor","total"]},"Content":{"type":"object","description":"One approved-content item — a menu item, a FAQ, a link, a listing, an event, an offer, a season or a guide. Its fields depend on the resource (see each operation); no organization or row id ever appears.","additionalProperties":true},"Error":{"type":"object","description":"The uniform error envelope; every 404 is byte-identical.","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}