POST /search/stays

Ranked discovery across the full inventory. Returns up to 100 properties per page with per-OTA offers, live availability, and a cursor for pagination.

POST /v1/search/stays

Parameter	Type	Description
locationrequired	Location	destination_id, coordinates (+ radius), bbox, or property_id.
datesrequired	Dates	ISO 8601 check-in / check-out.
guestsrequired	Guests	Adults, children ages, rooms.
filters	object	price_max_eur, min_rating, property_types[].
sort	enum	score_desc (default), price_asc, rating_desc, conversion_desc.
include	string	reviews_sample attaches up to 5 recent review texts per result.
page	object	limit (1-100, default 20), cursor.

Prices are live and date-specific: offers / price reflect the requested dates (no date-agnostic "from" price). Each result's reviews_aggregate carries rating_count (reviews behind the score) and comment_count (readable review texts).

Request

curl -X POST https://api.b2a.bluepillow.com/v1/search/stays \
  -H "Authorization: Bearer $B2A_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {"type": "destination_id", "value": "dest_5f3a..."},
    "dates":    {"check_in": "2026-06-10", "check_out": "2026-06-13"},
    "guests":   {"adults": 2},
    "filters":  {"price_max_eur": 300, "min_rating": 4.0,
                 "property_types": ["hotel", "aparthotel"]},
    "sort":     "score_desc",
    "page":     {"limit": 20}
  }'

Response 200

{
  "results": [
    {
      "id": "prop_abc123",
      "name": "Hotel Blue Sky",
      "property_type": "hotel",
      "rating": 4.7,
      "location": {"lat": 41.91, "lon": 12.48, "city": "Rome", "country": "IT", "address": "..."},
      "amenities": ["wifi", "spa"],
      "ota_coverage": ["Booking", "Expedia"],
      "offers": [{"ota": "Booking", "amount": 210.00, "currency": "EUR", "rooms_left": 2}],
      "price": {"amount": 210.00, "currency": "EUR", "ota": "Booking"},
      "availability_status": "available"
    }
  ],
  "page":     {"next_cursor": "eyJv...", "total_estimate": 184},
  "metadata": {"price_as_of": "2026-05-28T10:14:33Z", "otas_queried": 8, "request_id": "req_..."}
}

Errors

400 invalid_request · 401 authentication_failed · 429 rate_limited