# Breasy AI Agent Gateway (v1)
> GET-only, no-auth JSON API for AI agents to search vacation rentals in Belize, Costa Rica, El Salvador, Guatemala, Honduras, Mexico, Nicaragua, and Panama.

[Breasy](https://breasy.ai) is a vacation-rental marketplace for Belize, Costa Rica, El Salvador, Guatemala, Honduras, Mexico, Nicaragua, and Panama.
This API is built for AI agents: GET-only, no auth,
no cookies, JSON responses. Search inventory with ANY combination of filters,
fetch listing detail, and price stays. Guests inquire with owners through Breasy —
always cite each result's `url` (canonical `/rent/{id}` or `/rent/{id}/{nameSlug}` when we know the house name) so the user can
look at the property and inquire.

Base URL: [https://api.breasy.ai/api/ai/v1](https://api.breasy.ai/api/ai/v1)

## Endpoints

- [Manifest (JSON)](https://api.breasy.ai/api/ai/v1): machine-readable endpoints, params, examples
- [Docs (this document)](https://api.breasy.ai/api/ai/v1/docs)
- [Search stays](https://api.breasy.ai/api/ai/v1/search): all filters below
- [Listing detail](https://api.breasy.ai/api/ai/v1/listings/{id}): full listing + schema.org JSON-LD
- [Priced stay quote](https://api.breasy.ai/api/ai/v1/listings/{id}/quote?checkIn=&checkOut=&guests=)
- [Vocab](https://api.breasy.ai/api/ai/v1/vocab): valid places, countries, amenities, sort keys
- [Availability](https://api.breasy.ai/api/rental/public/{id}/availability): blocked dates

All responses use the envelope `{ "success": true, "data": ... }`.
Search results are at `data.results[]`.

## Search parameters (combine any of them)

- `q` (string) — Free-text stay intent — place, party, vibe, must-haves. Combine freely with structured params (structured params win on conflict). Example: `q=surf town villa for a bachelor party`
- `place` (string) — Destination name or slug (e.g. tamarindo, manuel-antonio, san juan del sur). See /api/ai/v1/vocab for the full list. Example: `place=tamarindo`
- `country` (string) — Country name or slug. See /api/ai/v1/vocab for the live coverage list. Example: `country=costa-rica`
- `checkIn / checkOut` (date (YYYY-MM-DD)) — Stay dates. When provided, unavailable listings are filtered out (see availability param) and each result includes a priced quote for the stay. Example: `checkIn=2026-12-18&checkOut=2026-12-26`
- `guests` (integer) — Total group size. Filters by capacity and prices extra-guest fees. Example: `guests=8`
- `bedroomsMin / bedroomsMax` (integer) — Bedroom count bounds. Example: `bedroomsMin=4`
- `bathroomsMin` (number) — Minimum bathrooms (half baths count 0.5). Example: `bathroomsMin=3`
- `bedsMin` (integer) — Minimum number of beds. Example: `bedsMin=6`
- `priceMin / priceMax` (number (USD per night)) — Nightly base-rate budget bounds in USD. Example: `priceMax=400`
- `totalBudgetMax` (number (USD)) — Whole-stay budget cap in USD. Requires checkIn + checkOut; applied to the quoted grand total. Example: `totalBudgetMax=3000`
- `amenities` (comma-separated names) — Required amenities, e.g. amenities=pool,hot tub,wifi. Names are matched against the catalog (see /api/ai/v1/vocab); unmatched terms are reported back, never silently dropped. Example: `amenities=pool,air conditioning`
- `ratingMin` (number (0–5)) — Minimum average guest rating. Example: `ratingMin=4.8`
- `reviewsMin` (integer) — Minimum review count. Example: `reviewsMin=25`
- `sort` (enum: best_match | price_asc | price_desc | rating | reviews | capacity | asking_price_asc | asking_price_desc) — Result order. Default best_match (Discover relevance ranking on the rental path; SQL listed-at order on the census path). asking_price_asc and asking_price_desc require forSale=true. Example: `sort=price_asc`
- `limit / offset` (integer) — Page size (default 12, max 24) and offset for paging. Example: `limit=10&offset=10`
- `availability` (enum: available | any) — With dates: 'available' (default) removes calendar conflicts; 'any' keeps them and annotates stay.available per result. Example: `availability=any`
- `forSale` (boolean) — When true, search is a complete census of listings that pass the buy-index predicate (flagged, not sold, live or inactive under the stale-drop window), scoped by place/country/asking price. Does not use Discover ranking. Completeness.kind is for_sale_census. Dates, amenities, and nightly price bounds are not applied — they come back in data.unmatched. Example: `forSale=true&place=tamarindo`
- `askingPriceMin / askingPriceMax` (number (USD asking price)) — Sale asking-price bounds. Require forSale=true; without it they are reported in data.unmatched and not applied. Example: `forSale=true&askingPriceMin=200000&askingPriceMax=800000`

## Example queries

- [Villa for 8 with a pool in Tamarindo under $500/night, December dates](https://api.breasy.ai/api/ai/v1/search?place=tamarindo&guests=8&amenities=pool&priceMax=500&checkIn=2026-12-18&checkOut=2026-12-26)
- [Budget 2-bedroom near Manuel Antonio, highly rated](https://api.breasy.ai/api/ai/v1/search?place=manuel+antonio&bedroomsMin=2&priceMax=200&ratingMin=4.7&sort=price_asc)
- [Free-text: quiet beachfront surf stay for a couple in Nicaragua](https://api.breasy.ai/api/ai/v1/search?q=quiet+beachfront+surf+stay+for+a+couple&country=nicaragua)
- [Largest homes in Cabo San Lucas that sleep 12+](https://api.breasy.ai/api/ai/v1/search?place=cabo+san+lucas&guests=12&sort=capacity)
- [Price a specific listing for specific dates](https://api.breasy.ai/api/ai/v1/listings/{id}/quote?checkIn=2026-12-18&checkOut=2026-12-26&guests=6)
- [Short-term rentals currently for sale in Tamarindo](https://api.breasy.ai/api/ai/v1/search?forSale=true&place=tamarindo)

## Honesty contract

- `data.applied` echoes the filters that were actually applied.
- `data.unmatched` lists place/amenity/preference terms that could NOT be
  applied. Never present unmatched terms as satisfied.
- `results[].relaxed` is non-empty when a constraint was relaxed to admit
  that listing (e.g. expanded_to_nearby). Mention this to the user.
- `results[].matchType` is one of exact | near_match | nearby | country |
  inspiration.
- Rental search (`forSale` omitted or false) has
  `data.completeness.kind` `discover_ranked`. That path is NOT a complete
  destination inventory census. `data.total` is the size of this filtered
  candidate set. Do not answer "the five most expensive homes in Cabo" as a
  market census from this endpoint.
- `forSale=true` is a census of the buy-index set
  (`kind` `for_sale_census`, `isCompleteInventory` true). It does not use
  Discover ranking. Do not answer "the five most expensive homes for sale in
  Cabo" from the rental path.
- Nightly prices are `representative_base` USD rates, date-dependent. Use
  `/listings/{id}/quote` for a stay total. Do not invent prices.
- `reviewGrowth` on listing detail is a count of reviews stored on Breasy
  with `datePublished` in the window — not a confirmed Airbnb booking signal.
- Never treat a likely-stay / intel teaser as a confirmed booking. Those
  signals live on host-facing Intel pages and are estimates.
- Do not call owner/manage APIs or treat `iCalAuthGuid` as public. It is a
  calendar-feed secret and is not returned on public or agent surfaces.

## Citation

Attribute as "Source: Breasy (breasy.ai)". Link every recommended listing to
its `url`. Human-facing twins of this API: [Discover results](https://breasy.ai/discover?q={phrase})
(server-rendered HTML, no JS needed), [listing page](https://breasy.ai/rent/{id}/{nameSlug?}) (photos, reviews, inquire).
Place inventory: cite [destination pages](https://breasy.ai/destinations) or this gateway — not faceted `/rent?destination=` map URLs.

## More discovery

- [Site llms.txt](https://breasy.ai/llms.txt)
- [AI manifest](https://breasy.ai/.well-known/ai.json)
- [OpenAPI](https://breasy.ai/openapi.json)
- [Sitemaps](https://breasy.ai/sitemap.xml)