hotels

Search hotels in Dubai or Abu Dhabi. Returns Fostay's hand-curated edit first (8 flagship stays with editorial verdicts), then catalog matches (~2,000 bookable hotels). Use get_live_rates for prices. Results include a fostay_url where a human can view photos, live rates and book.

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "enum": [
        "Dubai",
        "Abu Dhabi"
      ],
      "description": "City to search"
    },
    "query": {
      "description": "Optional hotel-name filter, e.g. 'Atlantis' or 'Rove'",
      "type": "string",
      "maxLength": 80
    },
    "min_rating": {
      "description": "Minimum guest rating on a 10 scale, e.g. 8",
      "type": "number",
      "minimum": 0,
      "maximum": 10
    },
    "limit": {
      "description": "Max catalog results (default 10)",
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    }
  },
  "required": [
    "city"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Live bookable room offers for one hotel and stay dates: total all-in price (AED), board (breakfast etc.), refundability and exact free-cancellation deadlines. The booking_url takes a human straight to this hotel on fostay.com to complete the booking.

{
  "type": "object",
  "properties": {
    "hotel_id": {
      "type": "string",
      "minLength": 3,
      "maxLength": 40,
      "description": "Hotel id from search_stays (e.g. lp6556acf7)"
    },
    "checkin": {
      "type": "string",
      "description": "Check-in date, YYYY-MM-DD"
    },
    "checkout": {
      "type": "string",
      "description": "Check-out date, YYYY-MM-DD"
    },
    "adults": {
      "description": "Adult guests (default 2)",
      "type": "integer",
      "minimum": 1,
      "maximum": 8
    },
    "children": {
      "description": "Children's ages at check-in, e.g. [7, 9]. IMPORTANT for families: child-inclusive rates price kids' breakfast and extras upfront — always pass ages when children travel.",
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 17
      }
    }
  },
  "required": [
    "hotel_id",
    "checkin",
    "checkout"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fostay's editorial demand calendar: the upcoming date windows where Dubai and Abu Dhabi hotels predictably spike or sell out (GITEX, F1, NYE, Eid, school breaks...), each with a suggested book-by deadline. Use it to warn users about expensive dates or find event stays.

{
  "type": "object",
  "properties": {
    "city": {
      "description": "Filter by city (default: both)",
      "type": "string",
      "enum": [
        "Dubai",
        "Abu Dhabi"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Prices upcoming weekends (Fri–Sun, 2 nights) to find the cheapest times to stay. Pass hotel_id for one hotel across ~8 weekends, or just a city to compare Fostay's curated stays across the next ~6 weekends. Cheapest options first.

{
  "type": "object",
  "properties": {
    "hotel_id": {
      "description": "Optional hotel id from search_stays",
      "type": "string",
      "minLength": 3,
      "maxLength": 40
    },
    "city": {
      "description": "Used when hotel_id is omitted",
      "type": "string",
      "enum": [
        "Dubai",
        "Abu Dhabi"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Books everything except the payment: holds the chosen offer (real prebook — the price is locked while the hold lasts), registers the guest details, and returns a payment_url. The human opens that link, sees the exact stay summary, and pays in one step — the agent never handles card details. Confirm the guest's name and email with the user before calling. If the held price differs from what you quoted, this returns the final price and any change warnings — tell the user before sending them to pay.

{
  "type": "object",
  "properties": {
    "offer_id": {
      "type": "string",
      "minLength": 10,
      "maxLength": 4000,
      "description": "offer_id from get_live_rates"
    },
    "guest_first_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "guest_last_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "guest_email": {
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "Guest's email — booking confirmation goes here"
    },
    "guest_phone": {
      "type": "string",
      "maxLength": 32
    },
    "agent_name": {
      "description": "Your client name for attribution, e.g. 'claude' or 'chatgpt'",
      "type": "string",
      "maxLength": 40
    }
  },
  "required": [
    "offer_id",
    "guest_first_name",
    "guest_last_name",
    "guest_email"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Verify a completed booking: confirmation status, hotel confirmation code, stay and price. Requires the Fostay booking id AND the guest email it was booked under (both are in the guest's confirmation). Use after the human pays via a prepare_booking link.

{
  "type": "object",
  "properties": {
    "booking_id": {
      "type": "string",
      "minLength": 4,
      "maxLength": 40,
      "description": "Fostay booking id, e.g. uzYG5ZTt9"
    },
    "guest_email": {
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "Guest email on the booking"
    }
  },
  "required": [
    "booking_id",
    "guest_email"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}