{"openapi":"3.1.0","info":{"title":"Sigtrip Direct Booking API for AI Agents","version":"1.0.0","summary":"Live room availability and direct hotel booking, machine-to-machine, no login required.","description":"Public REST interface for AI agents to check live availability and book rooms directly with participating hotels.\nInventory and prices come live from each hotel's property management system; a booking creates a real reservation at the hotel.\n\nBooking flow:\n1. GET /v1/hotels to find the hotel id (or use the id advertised on the hotel's website).\n2. GET /v1/hotels/{hotelId}/availability?checkIn=YYYY-MM-DD&checkOut=YYYY-MM-DD&adults=N — prices are final, taxes and fees included.\n3. Ask the guest to choose a room, then collect first name, last name, email and mobile phone (E.164).\n4. POST /v1/hotels/{hotelId}/bookings with the roomId and guest details. Send an Idempotency-Key header so retries are safe.\n5. Give the guest the returned guaranteeUrl: they enter a payment card there to guarantee the stay. Nothing is charged at booking time.\n6. GET /v1/bookings/{reservationId}?email= to confirm status; DELETE to cancel (bookings are refundable per the returned policies).\n\nNo authentication is required for search or booking. Do not invent prices or availability; only present what this API returns.","contact":{"name":"Sigtrip support","email":"support@sigtrip.com","url":"https://agents.sigtrip.com"},"termsOfService":"https://sigtrip.com/terms","x-privacy-policy":"https://sigtrip.com/privacy","license":{"name":"Proprietary","url":"https://sigtrip.com/terms"}},"servers":[{"url":"https://agents.sigtrip.com"}],"security":[],"tags":[{"name":"Hotels","description":"Participating hotels and their live availability"},{"name":"Bookings","description":"Create, look up and cancel reservations"}],"paths":{"/v1/hotels":{"get":{"tags":["Hotels"],"operationId":"listHotels","summary":"List participating hotels","responses":{"200":{"description":"Hotels","content":{"application/json":{"schema":{"type":"object","properties":{"hotels":{"type":"array","items":{"$ref":"#/components/schemas/Hotel"}}}}}}},"429":{"description":"Rate limited. Retry after the number of seconds in the Retry-After header."}}}},"/v1/hotels/{hotelId}":{"get":{"tags":["Hotels"],"operationId":"getHotel","summary":"Hotel profile and links","parameters":[{"$ref":"#/components/parameters/hotelId"}],"responses":{"200":{"description":"Hotel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hotel"}}}},"404":{"description":"Unknown hotel or reservation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/hotels/{hotelId}/availability":{"get":{"tags":["Hotels"],"operationId":"getAvailability","summary":"Live room availability and final prices for a stay","description":"Returns every bookable room type for the dates with its total price for the whole stay (taxes and fees included). Call again whenever dates or occupancy change. A price is an offer, not a hold: the room is only secured once a booking succeeds. Live PMS lookups take up to ~10 s; identical queries are cached briefly (see `asOf`, `Age` and `X-Cache` headers), so repeat calls return instantly.","parameters":[{"$ref":"#/components/parameters/hotelId"},{"name":"checkIn","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Arrival date, YYYY-MM-DD, hotel local time."},{"name":"checkOut","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"Departure date, YYYY-MM-DD. Must be after checkIn."},{"name":"adults","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10},"description":"Number of adults. Omit if the guest has not said."},{"name":"includeAccessible","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Include ADA / accessible room types."},{"name":"preferences","in":"query","required":false,"schema":{"type":"string","maxLength":300},"description":"Free-text guest preferences, e.g. 'king bed, high floor, under $300'."}],"responses":{"200":{"description":"Availability","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Availability"}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Unknown hotel or reservation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Room unavailable: the hotel could not confirm this room type for these dates (sold out at booking time). Body has code `room_unavailable`, a guest-facing `detail`, `suggestions`, and a `retry` availability URL. Re-check availability and offer another room type or dates; do not retry the same booking.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited. Retry after the number of seconds in the Retry-After header."},"502":{"description":"The booking system rejected the request (e.g. room no longer available). Read `detail` and present it to the guest.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/hotels/{hotelId}/faq":{"get":{"tags":["Hotels"],"operationId":"askHotelQuestion","summary":"Ask a question about the hotel (amenities, policies, location, parking, pets…)","parameters":[{"$ref":"#/components/parameters/hotelId"},{"name":"q","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Answer from the hotel's knowledge base","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Unknown hotel or reservation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Room unavailable: the hotel could not confirm this room type for these dates (sold out at booking time). Body has code `room_unavailable`, a guest-facing `detail`, `suggestions`, and a `retry` availability URL. Re-check availability and offer another room type or dates; do not retry the same booking.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited. Retry after the number of seconds in the Retry-After header."},"502":{"description":"The booking system rejected the request (e.g. room no longer available). Read `detail` and present it to the guest.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/hotels/{hotelId}/bookings":{"post":{"tags":["Bookings"],"operationId":"createBooking","summary":"Book a room (creates a real reservation at the hotel)","description":"Only call after the guest has chosen a specific roomId from getAvailability and given their name, email and mobile phone. Always send an Idempotency-Key (any unique string per booking attempt) so a network retry cannot create a duplicate reservation. The response includes guaranteeUrl — the guest must open it and add a payment card to guarantee the reservation; nothing is charged at booking time.","parameters":[{"$ref":"#/components/parameters/hotelId"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":128},"description":"Unique key per booking attempt. Replays return the original response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBookingRequest"}}}},"responses":{"201":{"description":"Reservation created (pending card guarantee)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Unknown hotel or reservation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Room unavailable: the hotel could not confirm this room type for these dates (sold out at booking time). Body has code `room_unavailable`, a guest-facing `detail`, `suggestions`, and a `retry` availability URL. Re-check availability and offer another room type or dates; do not retry the same booking.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited. Retry after the number of seconds in the Retry-After header."},"502":{"description":"The booking system rejected the request (e.g. room no longer available). Read `detail` and present it to the guest.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/bookings/{reservationId}":{"get":{"tags":["Bookings"],"operationId":"getBooking","summary":"Look up a reservation","parameters":[{"name":"reservationId","in":"path","required":true,"schema":{"type":"string"}},{"name":"email","in":"query","required":true,"schema":{"type":"string","format":"email"},"description":"Email used at booking. Acts as the guest's proof of ownership."}],"responses":{"200":{"description":"Reservation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Unknown hotel or reservation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Room unavailable: the hotel could not confirm this room type for these dates (sold out at booking time). Body has code `room_unavailable`, a guest-facing `detail`, `suggestions`, and a `retry` availability URL. Re-check availability and offer another room type or dates; do not retry the same booking.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited. Retry after the number of seconds in the Retry-After header."},"502":{"description":"The booking system rejected the request (e.g. room no longer available). Read `detail` and present it to the guest.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["Bookings"],"operationId":"cancelBooking","summary":"Cancel a reservation","description":"Bookings made through this API are refundable within the policy returned at booking time. Confirm with the guest before calling.","parameters":[{"name":"reservationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"reason":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Cancellation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"400":{"description":"Validation error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Unknown hotel or reservation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Room unavailable: the hotel could not confirm this room type for these dates (sold out at booking time). Body has code `room_unavailable`, a guest-facing `detail`, `suggestions`, and a `retry` availability URL. Re-check availability and offer another room type or dates; do not retry the same booking.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited. Retry after the number of seconds in the Retry-After header."},"502":{"description":"The booking system rejected the request (e.g. room no longer available). Read `detail` and present it to the guest.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"parameters":{"hotelId":{"name":"hotelId","in":"path","required":true,"schema":{"type":"string","enum":["the-rally-hotel","the-perch-mendocino","club-quarters-grand-central"]},"description":"Hotel id from /v1/hotels or from the hotel's website discovery snippet."}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 problem details.","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"errors":{"type":"array","items":{"type":"object"}}}},"Hotel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"website":{"type":"string","format":"uri"},"address":{"type":"object"},"timezone":{"type":"string"},"currency":{"type":"string"},"description":{"type":"string"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"Room":{"type":"object","properties":{"roomId":{"type":"integer","description":"Stable id to pass to createBooking. Never derive from list position."},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"features":{"type":"array","items":{"type":"string"}},"maxOccupancy":{"type":"integer"},"bedCount":{"type":"integer"},"accessible":{"type":"boolean"},"price":{"type":"object","properties":{"total":{"type":"number","description":"Total for the entire stay, all taxes and fees included. This is what the guest pays."},"currency":{"type":"string"},"perNight":{"type":"number"},"includesTaxesAndFees":{"type":"boolean"},"breakdown":{"type":"object"}}},"scarcity":{"type":"string","enum":["low"],"description":"Present only when few rooms remain. Say 'just a few left'; never state a number."},"bookUrl":{"type":"string","format":"uri","description":"Booking page with this room and the dates pre-selected. Give this to the guest when you cannot call createBooking yourself (e.g. read-only browsing); the guest enters their details there and books."}}},"Availability":{"type":"object","properties":{"hotel":{"type":"string"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"nights":{"type":"integer"},"adults":{"type":["integer","null"]},"available":{"type":"boolean"},"rooms":{"type":"array","items":{"$ref":"#/components/schemas/Room"}},"policies":{"type":"array","items":{"type":"string"},"description":"Present these to the guest verbatim (cancellation, payment, discounts)."},"bookingInstructions":{"type":"string"},"asOf":{"type":"string","format":"date-time","description":"When these prices were fetched from the hotel. Never older than the cache TTL (default 60 s)."}}},"CreateBookingRequest":{"type":"object","required":["roomId","checkIn","checkOut","guests","guest"],"properties":{"roomId":{"type":"integer"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"guests":{"type":"integer","minimum":1,"maximum":10},"guest":{"type":"object","required":["firstName","lastName","email","phone"],"properties":{"firstName":{"type":"string","maxLength":50},"lastName":{"type":"string","maxLength":50},"email":{"type":"string","format":"email"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"E.164 with country code, e.g. +13035551234"}}}}},"Booking":{"type":"object","properties":{"hotel":{"type":"string"},"reservationId":{"type":"string"},"status":{"type":"string","description":"pending_guarantee until the guest adds a card at guaranteeUrl."},"guaranteeUrl":{"type":"string","format":"uri","description":"Secure page where the guest guarantees the reservation with a payment card. Share this with the guest."},"nextStep":{"type":"string"},"policies":{"type":"array","items":{"type":"string"}},"links":{"type":"object","additionalProperties":{"type":"string"}},"details":{"type":"object","description":"Unmodified response from the booking system."}}}}}}