{"openapi":"3.1.0","info":{"title":"Quub agent API","version":"1.0.0","summary":"Hotel search anywhere, destination guides as data, and prebooking for a guest who pays on the booking partner page.","description":"Live hotel prices and rooms from Nuitee (LiteAPI), the booking partner and merchant of record, and Quub's sourced destination guides. Prices are the total for the whole stay for one room, taxes Nuitee collects included; taxes at the property are listed apart. Reads need no key. Prebook, reading a booking and cancelling need a free API key (POST /keys). Searches and prebooks with a key are priced at the agent margin: agent bookings carry an 8 percent margin. Nothing is charged by the API: the person named as guest pays on pay_url. https://quub.rent/for-agents","termsOfService":"https://quub.rent/terms","contact":{"name":"Quub","email":"hello@quub.rent","url":"https://quub.rent/for-agents"}},"servers":[{"url":"https://quub.rent/api/v1"}],"security":[{},{"bearer":[]}],"tags":[{"name":"hotels"},{"name":"guides"},{"name":"bookings"},{"name":"keys"}],"paths":{"/search":{"get":{"operationId":"searchHotels","tags":["hotels"],"summary":"Hotels with live prices for a place and dates","description":"place is a city, region, island, airport or landmark name anywhere, a destination slug (GET /destinations) or a Google place id.","security":[{},{"bearer":[]}],"parameters":[{"name":"place","in":"query","required":true,"schema":{"type":"string","example":"Lisbon"}},{"name":"checkin","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Check-in, YYYY-MM-DD, today or later."},{"name":"checkout","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Check-out, YYYY-MM-DD, 1 to 30 nights after check-in."},{"name":"adults","in":"query","schema":{"type":"integer","minimum":1,"maximum":8,"default":2},"description":"Adults in the one room."},{"name":"children","in":"query","schema":{"type":"string","example":"4,9"},"description":"Ages of children, comma separated, at most 4."},{"name":"currency","in":"query","schema":{"type":"string","default":"EUR","example":"USD"},"description":"ISO 4217 currency of the prices."},{"name":"nationality","in":"query","schema":{"type":"string","example":"GB"},"description":"Guest nationality, ISO 3166 alpha-2; default from Accept-Language, else NL."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":60,"default":20}},{"name":"sort","in":"query","schema":{"type":"string","enum":["price","rating"],"default":"price"}}],"responses":{"200":{"description":"Hotels, cheapest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/hotels/{id}":{"get":{"operationId":"getHotel","tags":["hotels"],"summary":"One hotel, and every bookable room for the dates","security":[{},{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"lp2d220"}},{"name":"checkin","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Check-in, YYYY-MM-DD, today or later."},{"name":"checkout","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Check-out, YYYY-MM-DD, 1 to 30 nights after check-in."},{"name":"adults","in":"query","schema":{"type":"integer","minimum":1,"maximum":8,"default":2},"description":"Adults in the one room.","required":false},{"name":"children","in":"query","schema":{"type":"string","example":"4,9"},"description":"Ages of children, comma separated, at most 4.","required":false},{"name":"currency","in":"query","schema":{"type":"string","default":"EUR","example":"USD"},"description":"ISO 4217 currency of the prices.","required":false},{"name":"nationality","in":"query","schema":{"type":"string","example":"GB"},"description":"Guest nationality, ISO 3166 alpha-2; default from Accept-Language, else NL.","required":false},{"name":"dest","in":"query","schema":{"type":"string"},"description":"A destination slug, so hotel_url opens the hotel under its guide."}],"responses":{"200":{"description":"The hotel and its rooms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HotelResult"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/destinations":{"get":{"operationId":"listDestinations","tags":["guides"],"summary":"Every destination guide","security":[{},{"bearer":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Filter by name, country or slug."}],"responses":{"200":{"description":"Destinations","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"destinations":{"type":"array","items":{"$ref":"#/components/schemas/DestinationSummary"}}}}}}},"429":{"$ref":"#/components/responses/Error"}}}},"/destinations/{slug}":{"get":{"operationId":"getDestinationGuide","tags":["guides"],"summary":"One guide's facts as data, each with its source","security":[{},{"bearer":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","example":"lisbon"}}],"responses":{"200":{"description":"The guide","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationGuide"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/prebook":{"post":{"operationId":"prebook","tags":["bookings"],"summary":"Hold a room for a guest and get the pay link","description":"Confirms the price with the hotel and opens a payment with Nuitee. The guest pays on pay_url; nothing is charged here. A repriced room comes back with price_changed true and previous_total, and the pay page asks the guest to confirm the new total.","security":[{"bearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"The same key within 24 hours returns the same booking."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrebookRequest"}}}},"responses":{"201":{"description":"Held; send pay_url to the guest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrebookResult"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/bookings/{id}":{"get":{"operationId":"getBooking","tags":["bookings"],"summary":"Status of a booking this key made","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"QTUW3GNACEXXX32"}},{"name":"email","in":"query","schema":{"type":"string","format":"email"},"description":"The guest email, or send X-Booking-Secret."},{"name":"X-Booking-Secret","in":"header","schema":{"type":"string"},"description":"booking_secret from prebook."}],"responses":{"200":{"description":"The booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/bookings/{id}/cancel":{"post":{"operationId":"cancelBooking","tags":["bookings"],"summary":"Cancel a refundable confirmed booking","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"The guest email."}}}}}},"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/keys":{"post":{"operationId":"requestApiKey","tags":["keys"],"summary":"Email a one-time link to a new API key","security":[{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"label":{"type":"string","maxLength":80}}}}}},"responses":{"202":{"description":"The link was sent","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"verification_sent"},"email":{"type":"string"},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A Quub API key, quub_ and 40 characters. X-API-Key is accepted too."}},"responses":{"Error":{"description":"An error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["bad_request","unauthorized","forbidden","not_found","conflict","rate_limited","daily_cap","unavailable","upstream","method_not_allowed"]},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}}}}},"Tax":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"description":{"type":["string","null"]}}},"Stay":{"type":"object","properties":{"checkin":{"type":"string"},"checkout":{"type":"string"},"nights":{"type":"integer"},"adults":{"type":"integer"},"children":{"type":"array","items":{"type":"integer"}},"currency":{"type":"string"},"nationality":{"type":"string"}}},"HotelCard":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["hotel","apartment","house"]},"stars":{"type":["number","null"]},"rating":{"type":["number","null"],"description":"Guest rating, 0 to 10."},"review_count":{"type":["integer","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"photo":{"type":["string","null"]},"area":{"type":"string"},"distance_km_from_centre":{"type":"number"},"room":{"type":["string","null"]},"price":{"type":"object","properties":{"total":{"type":["number","null"]},"currency":{"type":"string"},"per_night":{"type":["number","null"]},"taxes_included":{"type":"boolean"},"taxes_at_property":{"type":"array","items":{"$ref":"#/components/schemas/Tax"}}}},"board":{"type":["string","null"]},"breakfast":{"type":"boolean"},"refundable":{"type":"boolean"},"free_cancellation_until":{"type":["string","null"],"format":"date-time"},"offer_id":{"type":["string","null"]},"hotel_url":{"type":"string"},"book_url":{"type":"string"},"sandbox":{"type":"boolean"}}},"SearchResult":{"type":"object","properties":{"place":{"type":"object","properties":{"name":{"type":"string"},"country":{"type":["string","null"]},"destination":{"type":"string"},"guide_url":{"type":"string"},"guide_api":{"type":"string"},"place_id":{"type":["string","null"]}}},"stay":{"$ref":"#/components/schemas/Stay"},"count":{"type":"integer"},"hotels":{"type":"array","items":{"$ref":"#/components/schemas/HotelCard"}},"checked":{"type":"string","format":"date-time"},"priced_for":{"type":"string","enum":["public","agent key"]},"notes":{"type":"array","items":{"type":"string"}}}},"Rate":{"type":"object","properties":{"offer_id":{"type":"string"},"room":{"type":"string"},"board":{"type":"string"},"breakfast":{"type":"boolean"},"refundable":{"type":"boolean"},"free_cancellation_until":{"type":["string","null"],"format":"date-time"},"max_occupancy":{"type":["integer","null"]},"total":{"type":"number"},"per_night":{"type":"number"},"currency":{"type":"string"},"taxes_included":{"type":"array","items":{"$ref":"#/components/schemas/Tax"}},"taxes_at_property":{"type":"array","items":{"$ref":"#/components/schemas/Tax"}},"book_url":{"type":"string"}}},"HotelResult":{"type":"object","properties":{"hotel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":["string","null"]},"stars":{"type":["number","null"]},"rating":{"type":["number","null"]},"review_count":{"type":["integer","null"]},"address":{"type":"string"},"city":{"type":"string"},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"checkin_from":{"type":["string","null"]},"checkout_by":{"type":["string","null"]},"parking":{"type":["string","null"]},"photos":{"type":"array","items":{"type":"string"}},"description":{"type":"array","items":{"type":"string"}},"important_information":{"type":"array","items":{"type":"string"}},"facilities":{"type":"array","items":{"type":"string"}},"hotel_url":{"type":"string"}}},"stay":{"$ref":"#/components/schemas/Stay"},"rates":{"type":"array","items":{"$ref":"#/components/schemas/Rate"}},"rates_error":{"type":"string"},"priced_for":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}},"DestinationSummary":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"description":{"type":"string"},"updated":{"type":"string"},"guide_url":{"type":"string"},"api_url":{"type":"string"}}},"Fact":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"source":{"type":"string"}}},"DestinationGuide":{"allOf":[{"$ref":"#/components/schemas/DestinationSummary"},{"type":"object","properties":{"title":{"type":"string"},"lede":{"type":"string"},"key_facts":{"type":"object","description":"tourist_tax, short_term_rental_rules, guest_registration, parking, monthly_stays, airport, emergency_number when the guide has them.","additionalProperties":{"$ref":"#/components/schemas/Fact"}},"facts":{"type":"array","items":{"$ref":"#/components/schemas/Fact"}},"areas":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"suits":{"type":"string"},"parking_and_car_access":{"type":"string"},"stay_types":{"type":"array","items":{"type":"string"}},"near":{"type":"array","items":{"type":"object","properties":{"to":{"type":"string"},"distance":{"type":"string"}}}}}}},"articles":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"updated":{"type":"string"}}}},"faq":{"type":"array","items":{"type":"object","properties":{"q":{"type":"string"},"a":{"type":"string"}}}},"sources":{"type":"array","items":{"type":"string"}},"search":{"type":"string"},"car_rental":{"type":"string"}}}]},"PrebookRequest":{"type":"object","required":["offer_id","hotel_id","checkin","checkout","guest"],"properties":{"offer_id":{"type":"string"},"hotel_id":{"type":"string"},"checkin":{"type":"string","format":"date"},"checkout":{"type":"string","format":"date"},"adults":{"type":"integer","minimum":1,"maximum":8,"default":2},"currency":{"type":"string","default":"EUR"},"nationality":{"type":"string"},"expected_total":{"type":"number","description":"The total the agent saw; a different prebook total is flagged."},"guest":{"type":"object","required":["first_name","last_name","email","phone"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","example":"+31 6 1234 5678"}}},"remarks":{"type":"string","maxLength":500}}},"Booking":{"type":"object","properties":{"booking_id":{"type":"string"},"status":{"type":"string","enum":["awaiting_payment","confirming","confirmed","outcome_pending","failed","cancelled"]},"hotel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":["string","null"]}}},"checkin":{"type":"string"},"checkout":{"type":"string"},"adults":{"type":"integer"},"room":{"type":"string"},"board":{"type":"string"},"total":{"type":"number"},"currency":{"type":"string"},"taxes_at_property":{"type":"array","items":{"$ref":"#/components/schemas/Tax"}},"refundable":{"type":"boolean"},"free_cancellation_until":{"type":["string","null"]},"cancellation_terms":{"type":"string"},"guest":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"}}},"pay_url":{"type":"string"},"confirmation_number":{"type":"string"},"hotel_reference":{"type":"string"},"voucher_url":{"type":"string"},"refund_amount":{"type":["number","null"]},"cancellation_fee":{"type":["number","null"]},"booking_url":{"type":"string"},"created":{"type":"string"},"updated":{"type":"string"}}},"PrebookResult":{"allOf":[{"$ref":"#/components/schemas/Booking"},{"type":"object","properties":{"booking_secret":{"type":"string","description":"Shown once."},"price_changed":{"type":"boolean"},"previous_total":{"type":"number"},"pay_url":{"type":"string"},"pay_within_minutes":{"type":"integer"},"expires_at":{"type":"string","format":"date-time","description":"Advisory."},"terms_url":{"type":"string"},"next_step":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}]}}},"externalDocs":{"url":"https://quub.rent/for-agents","description":"Quub for AI agents"},"x-mcp-server":"https://quub.rent/mcp"}