{"openapi":"3.1.0","info":{"title":"BE-A Hotel Availability API","description":"Real-time hotel availability and pricing search for hotels managed by BE-A.\n\nThis API enables direct bookings with hotels — with real-time data, directly from hotels.\n\nUnlike OTA platforms, this API provides:\n- Real-time availability from hotel management systems\n- Direct pricing without commission markups\n- Multi-strategy search for optimal availability\n\n**Usage Flow:**\n1. Use `/hotels` to discover available hotels (optionally filter by country/city)\n2. Use `/availability` to check room availability and pricing for specific hotels\n\n**Important - Room-per-room queries for large groups:**\nAvailability is checked on a room-by-room basis. For groups larger than typical room capacity:\n- For 5 guests: Query for 5 (check single room), then 2 and 3 (two-room options)\n- For 10+ guests: Query for 2, 3, and 4 guests (to find multi-room combinations)\n\n**Test Environment Data:**\nThis test instance contains hotels in: Czech Republic (Prague, Brno), Austria (Vienna)\n\n**Note:** Use the exact hotel name and city from `/hotels` when calling `/availability`.","version":"1.0.0"},"servers":[{"url":"https://beamcpserverprod.azurewebsites.net","description":"Current environment (beamcpserverprod)"}],"paths":{"/hotels":{"get":{"tags":["Hotels"],"summary":"List available hotels","description":"Get a list of hotels, optionally filtered by country, city, and/or geographic bounding box.","operationId":"list_hotels_hotels_get","parameters":[{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Country name to filter by","title":"Country"},"description":"Country name to filter by"},{"name":"city","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"City name to filter by","title":"City"},"description":"City name to filter by"},{"name":"sw_lat","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Southwest corner latitude for bounding-box search","title":"Sw Lat"},"description":"Southwest corner latitude for bounding-box search"},{"name":"sw_lng","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Southwest corner longitude for bounding-box search","title":"Sw Lng"},"description":"Southwest corner longitude for bounding-box search"},{"name":"ne_lat","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Northeast corner latitude for bounding-box search","title":"Ne Lat"},"description":"Northeast corner latitude for bounding-box search"},{"name":"ne_lng","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Northeast corner longitude for bounding-box search","title":"Ne Lng"},"description":"Northeast corner longitude for bounding-box search"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Hotel"},"title":"Response List Hotels Hotels Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-openai-isConsequential":false}},"/availability":{"get":{"tags":["Availability"],"summary":"Check room availability","description":"Get available room offers for a hotel on specific dates with guest counts.","operationId":"get_availability_availability_get","parameters":[{"name":"hotel_name","in":"query","required":true,"schema":{"type":"string","maxLength":200,"description":"Hotel name from /hotels endpoint","title":"Hotel Name"},"description":"Hotel name from /hotels endpoint"},{"name":"city","in":"query","required":true,"schema":{"type":"string","maxLength":100,"description":"City where the hotel is located","title":"City"},"description":"City where the hotel is located"},{"name":"check_in_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date in YYYY-MM-DD format","title":"Check In Date"},"description":"Check-in date in YYYY-MM-DD format"},{"name":"check_out_date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date in YYYY-MM-DD format","title":"Check Out Date"},"description":"Check-out date in YYYY-MM-DD format"},{"name":"adults_count","in":"query","required":true,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Number of adult guests (minimum 1)","title":"Adults Count"},"description":"Number of adult guests (minimum 1)"},{"name":"children_count","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":0,"description":"Number of children aged 0-17","default":0,"title":"Children Count"},"description":"Number of children aged 0-17"},{"name":"children_ages","in":"query","required":false,"schema":{"type":"array","items":{"type":"integer"},"description":"Age of each child (0-17)","default":[],"title":"Children Ages"},"description":"Age of each child (0-17)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Availability Availability Get","$ref":"#/components/schemas/AvailabilityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-openai-isConsequential":false}},"/images/{hotel_id}.jpg":{"get":{"tags":["Hotels"],"summary":"Get hotel image","description":"Serve a hotel image by hotel ID.","operationId":"get_hotel_image_images__hotel_id__jpg_get","parameters":[{"name":"hotel_id","in":"path","required":true,"schema":{"type":"string","title":"Hotel Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}},"image/jpeg":{}}},"404":{"description":"Image not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-openai-isConsequential":false}},"/health":{"get":{"tags":["System"],"summary":"Health check","description":"Simple health check endpoint to verify the API is running.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"x-openai-isConsequential":false}},"/terms-of-service.txt":{"get":{"tags":["System"],"summary":"Terms of Service","description":"View the Terms of Service for the BE-A Hotel Availability Search service.","operationId":"get_terms_of_service_terms_of_service_txt_get","responses":{"200":{"description":"Successful Response"}},"x-openai-isConsequential":false}},"/.well-known/openai-apps-challenge":{"get":{"tags":["System"],"summary":"OpenAI Apps Verification","description":"OpenAI Apps directory verification token.","operationId":"get_openai_apps_challenge__well_known_openai_apps_challenge_get","responses":{"200":{"description":"Successful Response"}},"x-openai-isConsequential":false}}},"components":{"schemas":{"AvailabilityQuery":{"properties":{"check_in_date":{"type":"string","title":"Check In Date"},"check_out_date":{"type":"string","title":"Check Out Date"},"adults_count":{"type":"integer","title":"Adults Count"},"children_count":{"type":"integer","title":"Children Count"},"children_ages":{"items":{"type":"integer"},"type":"array","title":"Children Ages"}},"type":"object","required":["check_in_date","check_out_date","adults_count","children_count","children_ages"],"title":"AvailabilityQuery"},"AvailabilityResponse":{"properties":{"status":{"type":"string","title":"Status"},"result_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Type"},"hotel_name":{"type":"string","title":"Hotel Name"},"hotel_city":{"type":"string","title":"Hotel City"},"hotel_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hotel Country"},"query":{"$ref":"#/components/schemas/AvailabilityQuery"},"suggested_check_out":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Suggested Check Out"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes"},"offers":{"items":{"$ref":"#/components/schemas/RoomOffer"},"type":"array","title":"Offers"},"errors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Errors"}},"type":"object","required":["status","result_type","hotel_name","hotel_city","hotel_country","query","suggested_check_out","notes","offers"],"title":"AvailabilityResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Hotel":{"properties":{"hotel_id":{"type":"string","title":"Hotel Id","description":"Unique hotel identifier"},"name":{"type":"string","title":"Name","description":"Hotel name"},"country":{"type":"string","title":"Country","description":"Country where the hotel is located"},"city":{"type":"string","title":"City","description":"City where the hotel is located"},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude","description":"GPS latitude"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude","description":"GPS longitude"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"URL path to hotel image"},"location_description":{"type":"string","title":"Location Description","description":"Description of hotel location"},"hotel_description":{"type":"string","title":"Hotel Description","description":"Description of the hotel"},"website_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website Url","description":"Public hotel website URL"},"contacts":{"$ref":"#/components/schemas/HotelContact","description":"Hotel contact information"}},"type":"object","required":["hotel_id","name","country","city","location_description","hotel_description","contacts"],"title":"Hotel"},"HotelContact":{"properties":{"email":{"items":{"type":"string"},"type":"array","title":"Email","description":"Email addresses"},"whatsapp":{"items":{"type":"string"},"type":"array","title":"Whatsapp","description":"WhatsApp numbers"},"phone":{"items":{"type":"string"},"type":"array","title":"Phone","description":"Phone numbers"}},"type":"object","required":["email","whatsapp","phone"],"title":"HotelContact"},"RatePlan":{"properties":{"rate_plan_id":{"type":"string","title":"Rate Plan Id","default":""},"name":{"type":"string","title":"Name","default":""},"cancellation_policy":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancellation Policy","description":"Cancellation conditions for this rate"}},"additionalProperties":true,"type":"object","title":"RatePlan"},"RoomOffer":{"properties":{"room_type":{"$ref":"#/components/schemas/RoomType"},"rate_plan":{"$ref":"#/components/schemas/RatePlan"},"total_price":{"anyOf":[{"type":"number"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Total Price"},"currency":{"type":"string","title":"Currency","default":""},"available_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Available Count"},"reservation_link":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reservation Link","description":"Direct booking URL for this offer"}},"additionalProperties":true,"type":"object","title":"RoomOffer"},"RoomType":{"properties":{"room_type_id":{"type":"string","title":"Room Type Id","default":""},"name":{"type":"string","title":"Name","default":""},"occupancy":{"type":"integer","title":"Occupancy","default":1}},"additionalProperties":true,"type":"object","title":"RoomType"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}