# Breasy AI Agent Gateway (v1)

Breasy (https://breasy.ai) is a vacation-rental marketplace for Costa Rica, Nicaragua, Mexico, Panama, Belize, El Salvador, and Honduras.
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. Humans make the final booking decision —
always cite each result's `url` (https://breasy.ai/rent/{id}) so the user can
look at the property and book.

Base URL: https://api.breasy.ai/api/ai/v1

## Endpoints

- `GET https://api.breasy.ai/api/ai/v1` — machine-readable manifest (JSON)
- `GET https://api.breasy.ai/api/ai/v1/docs` — this document
- `GET https://api.breasy.ai/api/ai/v1/search` — search stays (all filters below)
- `GET https://api.breasy.ai/api/ai/v1/listings/{id}` — full listing detail + schema.org JSON-LD
- `GET https://api.breasy.ai/api/ai/v1/listings/{id}/quote?checkIn=&checkOut=&guests=` — priced stay quote
- `GET https://api.breasy.ai/api/ai/v1/vocab` — valid places, countries, amenities, sort keys
- `GET 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: costa-rica, nicaragua, mexico, panama, belize, el-salvador, honduras. 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) — Result order. Default best_match (Discover relevance ranking). 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`

## 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

## 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.
- `data.completeness.kind` is `discover_ranked`. Search 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.
- 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: https://breasy.ai/discover?q={phrase}
(server-rendered HTML, no JS needed), https://breasy.ai/rent/{id} (listing page
with photos, reviews, booking).

## More discovery

- 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