POST /decide

Aggregate, rank, and return one booking decision for a travel intent. Stateless — no session, no cursors. Up to five alternatives included for fallback.

POST /v1/decide

Parameter	Type	Description
locationrequired	Location	type: destination_id \| poi_id \| coordinates \| bbox \| property_id.
datesrequired	Dates	check_in, check_out (ISO 8601 date).
guestsrequired	Guests	adults (1-16), children_ages[], rooms (1-9).
constraints	Constraints	price/rating filters, cancellation, preferred/excluded OTAs.
context	Context	end_user_country (ISO 3166-1 α2), currency (ISO 4217).

Request

curl -X POST https://api.b2a.bluepillow.com/v1/decide \
  -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, "rooms": 1},
    "constraints": {"price_max_eur": 250, "min_rating": 4.0},
    "context":  {"end_user_country": "IT", "currency": "EUR", "language": "en"}
  }'

Response 200

{
  "recommended": {
    "property": {
      "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", "breakfast"],
      "ota_coverage": ["Booking", "Expedia"],
      "price": {"amount": 210.00, "currency": "EUR", "ota": "Booking", "refundable": true},
      "availability_status": "available"
    }
  },
  "alternatives": [/* up to 5 more */],
  "metadata": {
    "price_as_of": "2026-05-28T10:14:33Z",
    "total_options_considered": 47,
    "request_id": "req_01HXYZ..."
  }
}

Errors

400 invalid_request · 401 authentication_failed · 404 no_offers_found · 429 rate_limited