> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardrift.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Bookings > The user's bookings — imported from email (Gmail scan, forwarded confirmations, in-chat paste) and sold first-party — in the exact shape the in-app Bookings page renders, so a flight comes back with its card_data and its editable ExtractedFlight. ## OpenAPI ````yaml /openapi.json get /v1/bookings openapi: 3.1.0 info: title: Stardrift API description: >- Read and edit the authenticated user's trips, itineraries, recorded bookings, and saved lists. Private records are owner-scoped. MCP tool names are documented separately from these HTTP operations. version: v1 servers: - url: https://stardrift.ai/api security: [] paths: /v1/bookings: get: tags: - mcp-server summary: List Bookings description: |- The user's bookings — imported from email (Gmail scan, forwarded confirmations, in-chat paste) and sold first-party — in the exact shape the in-app Bookings page renders, so a flight comes back with its card_data and its editable ExtractedFlight. operationId: list_bookings_v1_bookings_get parameters: - name: booking_type in: query required: false schema: anyOf: - enum: - flight - hotel - rail - road - car_rental - event type: string - type: 'null' title: Booking Type - name: trip_id in: query required: false schema: anyOf: - type: string format: uuid - type: 'null' title: Trip Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BookingsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: BookingsResponse: properties: bookings: items: oneOf: - $ref: '#/components/schemas/FlightBookingItem' - $ref: '#/components/schemas/HotelBookingItem' - $ref: '#/components/schemas/RailBookingItem' - $ref: '#/components/schemas/RoadBookingItem' - $ref: '#/components/schemas/CarRentalBookingItem' - $ref: '#/components/schemas/EventBookingItem' discriminator: propertyName: booking_type mapping: car_rental: $ref: '#/components/schemas/CarRentalBookingItem' event: $ref: '#/components/schemas/EventBookingItem' flight: $ref: '#/components/schemas/FlightBookingItem' hotel: $ref: '#/components/schemas/HotelBookingItem' rail: $ref: '#/components/schemas/RailBookingItem' road: $ref: '#/components/schemas/RoadBookingItem' type: array title: Bookings type: object required: - bookings title: BookingsResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError FlightBookingItem: properties: id: type: string title: Id event_date: anyOf: - type: string - type: 'null' title: Event Date created_at: type: string title: Created At confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number status: type: string enum: - active - cancelled title: Status default: active gmail_link: anyOf: - type: string - type: 'null' title: Gmail Link import_kind: anyOf: - type: string enum: - email - image - text - type: 'null' title: Import Kind import_link: anyOf: - type: string - type: 'null' title: Import Link import_sources: items: $ref: '#/components/schemas/ImportSource' type: array title: Import Sources source: type: string enum: - email_import - first_party title: Source default: email_import trip_id: anyOf: - type: string - type: 'null' title: Trip Id trip_title: anyOf: - type: string - type: 'null' title: Trip Title review: anyOf: - $ref: '#/components/schemas/BookingReview' - type: 'null' booking_type: type: string const: flight title: Booking Type default: flight card_data: $ref: '#/components/schemas/FlightCardData' edit_data: $ref: '#/components/schemas/ExtractedFlight' type: object required: - id - event_date - created_at - confirmation_number - card_data - edit_data title: FlightBookingItem HotelBookingItem: properties: id: type: string title: Id event_date: anyOf: - type: string - type: 'null' title: Event Date created_at: type: string title: Created At confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number status: type: string enum: - active - cancelled title: Status default: active gmail_link: anyOf: - type: string - type: 'null' title: Gmail Link import_kind: anyOf: - type: string enum: - email - image - text - type: 'null' title: Import Kind import_link: anyOf: - type: string - type: 'null' title: Import Link import_sources: items: $ref: '#/components/schemas/ImportSource' type: array title: Import Sources source: type: string enum: - email_import - first_party title: Source default: email_import trip_id: anyOf: - type: string - type: 'null' title: Trip Id trip_title: anyOf: - type: string - type: 'null' title: Trip Title review: anyOf: - $ref: '#/components/schemas/BookingReview' - type: 'null' booking_type: type: string const: hotel title: Booking Type default: hotel card_data: $ref: '#/components/schemas/HotelCardData' type: object required: - id - event_date - created_at - confirmation_number - card_data title: HotelBookingItem RailBookingItem: properties: id: type: string title: Id event_date: anyOf: - type: string - type: 'null' title: Event Date created_at: type: string title: Created At confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number status: type: string enum: - active - cancelled title: Status default: active gmail_link: anyOf: - type: string - type: 'null' title: Gmail Link import_kind: anyOf: - type: string enum: - email - image - text - type: 'null' title: Import Kind import_link: anyOf: - type: string - type: 'null' title: Import Link import_sources: items: $ref: '#/components/schemas/ImportSource' type: array title: Import Sources source: type: string enum: - email_import - first_party title: Source default: email_import trip_id: anyOf: - type: string - type: 'null' title: Trip Id trip_title: anyOf: - type: string - type: 'null' title: Trip Title review: anyOf: - $ref: '#/components/schemas/BookingReview' - type: 'null' booking_type: type: string const: rail title: Booking Type default: rail card_data: $ref: '#/components/schemas/ImportedRailCardData' type: object required: - id - event_date - created_at - confirmation_number - card_data title: RailBookingItem RoadBookingItem: properties: id: type: string title: Id event_date: anyOf: - type: string - type: 'null' title: Event Date created_at: type: string title: Created At confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number status: type: string enum: - active - cancelled title: Status default: active gmail_link: anyOf: - type: string - type: 'null' title: Gmail Link import_kind: anyOf: - type: string enum: - email - image - text - type: 'null' title: Import Kind import_link: anyOf: - type: string - type: 'null' title: Import Link import_sources: items: $ref: '#/components/schemas/ImportSource' type: array title: Import Sources source: type: string enum: - email_import - first_party title: Source default: email_import trip_id: anyOf: - type: string - type: 'null' title: Trip Id trip_title: anyOf: - type: string - type: 'null' title: Trip Title review: anyOf: - $ref: '#/components/schemas/BookingReview' - type: 'null' booking_type: type: string const: road title: Booking Type default: road card_data: $ref: '#/components/schemas/RoadCardData' type: object required: - id - event_date - created_at - confirmation_number - card_data title: RoadBookingItem CarRentalBookingItem: properties: id: type: string title: Id event_date: anyOf: - type: string - type: 'null' title: Event Date created_at: type: string title: Created At confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number status: type: string enum: - active - cancelled title: Status default: active gmail_link: anyOf: - type: string - type: 'null' title: Gmail Link import_kind: anyOf: - type: string enum: - email - image - text - type: 'null' title: Import Kind import_link: anyOf: - type: string - type: 'null' title: Import Link import_sources: items: $ref: '#/components/schemas/ImportSource' type: array title: Import Sources source: type: string enum: - email_import - first_party title: Source default: email_import trip_id: anyOf: - type: string - type: 'null' title: Trip Id trip_title: anyOf: - type: string - type: 'null' title: Trip Title review: anyOf: - $ref: '#/components/schemas/BookingReview' - type: 'null' booking_type: type: string const: car_rental title: Booking Type default: car_rental card_data: $ref: '#/components/schemas/CarRentalCardData' type: object required: - id - event_date - created_at - confirmation_number - card_data title: CarRentalBookingItem EventBookingItem: properties: id: type: string title: Id event_date: anyOf: - type: string - type: 'null' title: Event Date created_at: type: string title: Created At confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number status: type: string enum: - active - cancelled title: Status default: active gmail_link: anyOf: - type: string - type: 'null' title: Gmail Link import_kind: anyOf: - type: string enum: - email - image - text - type: 'null' title: Import Kind import_link: anyOf: - type: string - type: 'null' title: Import Link import_sources: items: $ref: '#/components/schemas/ImportSource' type: array title: Import Sources source: type: string enum: - email_import - first_party title: Source default: email_import trip_id: anyOf: - type: string - type: 'null' title: Trip Id trip_title: anyOf: - type: string - type: 'null' title: Trip Title review: anyOf: - $ref: '#/components/schemas/BookingReview' - type: 'null' booking_type: type: string const: event title: Booking Type default: event card_data: $ref: '#/components/schemas/AttractionDisplayData' type: object required: - id - event_date - created_at - confirmation_number - card_data title: EventBookingItem 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 ImportSource: properties: kind: type: string enum: - email - image - text title: Kind link: anyOf: - type: string - type: 'null' title: Link created_at: type: string format: date-time title: Created At type: object required: - kind - created_at title: ImportSource description: >- One source that fed an imported booking — an `email_import_items` row. `link` is the Gmail deep link or the image's API path; None for a forward and for pasted text. BookingReview: properties: question: type: string enum: - which_trip - is_this_yours title: Question travelers: items: type: string type: array title: Travelers default: [] nudge: type: boolean title: Nudge default: false type: object required: - question title: BookingReview FlightCardData: properties: type: type: string enum: - one-way - round-trip - multi-city title: Type journeys: items: $ref: '#/components/schemas/JourneyDisplay' type: array title: Journeys cash_details: anyOf: - $ref: '#/components/schemas/CashDisplay' - type: 'null' cabin_class: anyOf: - type: string - type: 'null' title: Cabin Class booking_links: anyOf: - items: $ref: '#/components/schemas/BookingLink' type: array - type: 'null' title: Booking Links adults: type: integer title: Adults default: 1 children: type: integer title: Children default: 0 booking_token: anyOf: - type: string - type: 'null' title: Booking Token departure_token: anyOf: - type: string - type: 'null' title: Departure Token return_date: anyOf: - type: string - type: 'null' title: Return Date __index: type: integer title: Index __tool_call_id: type: string title: Tool Call Id message_id: anyOf: - type: string - type: 'null' title: Message Id booking_links_status: anyOf: - type: string - type: 'null' title: Booking Links Status confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number is_booked: type: boolean title: Is Booked default: false is_user_import: type: boolean title: Is User Import default: false user_edited: type: boolean title: User Edited default: false award_details: anyOf: - additionalProperties: true type: object - type: 'null' title: Award Details type: object required: - type - journeys - __index - __tool_call_id title: FlightCardData description: >- Flight card data for frontend - wraps Journey with card metadata. This is the serialization format sent to the frontend FlightCard component. It converts from the internal Journey model to the frontend contract. ExtractedFlight: properties: type: type: string enum: - one-way - round-trip title: Type default: one-way outbound_segments: items: $ref: '#/components/schemas/ExtractedFlightSegment' type: array minItems: 1 title: Outbound Segments description: Segments going TO the destination return_segments: items: $ref: '#/components/schemas/ExtractedFlightSegment' type: array title: Return Segments description: Segments coming BACK from destination (empty for one-way) price: anyOf: - type: number - type: 'null' title: Price description: Total cash price if mentioned (null if fully award-booked) currency: type: string pattern: ^[A-Z]{3}$ title: Currency description: ISO 4217 currency code (e.g., USD, EUR, JPY) default: USD award: anyOf: - $ref: '#/components/schemas/AwardPayment' - type: 'null' description: Loyalty miles/points payment, if applicable confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number booking_reference: anyOf: - type: string - type: 'null' title: Booking Reference description: >- Airline PNR / record locator (6-char alphanumeric, e.g., 'ABCDEF'). Different from confirmation_number which may be an OTA/agent booking code. eticket_number: anyOf: - type: string - type: 'null' title: Eticket Number description: E-ticket number (typically 13 digits, e.g., '0012345678901') fare_class: anyOf: - type: string - type: 'null' title: Fare Class description: Fare/booking class letter (e.g., 'Y', 'B', 'J', 'W') checked_bags: anyOf: - type: integer - type: 'null' title: Checked Bags description: Number of checked bags included or purchased carry_on_bags: anyOf: - type: integer - type: 'null' title: Carry On Bags description: Number of carry-on bags included check_in_url: anyOf: - type: string - type: 'null' title: Check In Url description: Online check-in URL if present in the email oag_enriched_at: anyOf: - type: string - type: 'null' title: Oag Enriched At description: ISO timestamp when OAG enrichment was applied passenger_count: anyOf: - type: integer - type: 'null' title: Passenger Count description: Number of adult passengers on this booking (e.g., 2 passengers) passenger_names: items: type: string type: array title: Passenger Names description: Names of passengers if listed (e.g., ['John Smith', 'Jane Smith']) children: anyOf: - type: integer - type: 'null' title: Children description: Number of child passengers (aged 2-11) infants: anyOf: - type: integer - type: 'null' title: Infants description: Number of infant passengers (under 2) type: object required: - outbound_segments title: ExtractedFlight description: |- Complete flight booking extracted from user message. For one-way: all segments in outbound_segments, return_segments empty For round-trip: outbound_segments has flights TO destination, return_segments has flights BACK from destination HotelCardData: properties: name: type: string title: Name price: anyOf: - type: number - type: 'null' title: Price price_display: anyOf: - type: string - type: 'null' title: Price Display price_before_taxes: anyOf: - type: number - type: 'null' title: Price Before Taxes total_price: anyOf: - type: number - type: 'null' title: Total Price total_price_display: anyOf: - type: string - type: 'null' title: Total Price Display rating: anyOf: - type: number - type: 'null' title: Rating reviews: anyOf: - type: integer - type: 'null' title: Reviews hotel_class: anyOf: - type: integer - type: 'null' title: Hotel Class link: anyOf: - type: string - type: 'null' title: Link description: anyOf: - type: string - type: 'null' title: Description check_in_time: anyOf: - type: string - type: 'null' title: Check In Time check_out_time: anyOf: - type: string - type: 'null' title: Check Out Time amenities: items: type: string type: array title: Amenities essential_info: items: type: string type: array title: Essential Info latitude: anyOf: - type: number - type: 'null' title: Latitude longitude: anyOf: - type: number - type: 'null' title: Longitude location_rating: anyOf: - type: number - type: 'null' title: Location Rating nearby_places: items: additionalProperties: true type: object type: array title: Nearby Places currency: type: string title: Currency default: USD property_token: anyOf: - type: string - type: 'null' title: Property Token thumbnail: anyOf: - type: string - type: 'null' title: Thumbnail thumbnail_thumbhash: anyOf: - type: string - type: 'null' title: Thumbnail Thumbhash price_tier: anyOf: - type: string - type: 'null' title: Price Tier source: anyOf: - type: string - type: 'null' title: Source feed: anyOf: - type: string enum: - b2c - cug - type: 'null' title: Feed hotel_id: anyOf: - type: string - type: 'null' title: Hotel Id rooms: items: $ref: '#/components/schemas/RoomOption' type: array title: Rooms __index: type: integer title: Index __tool_call_id: type: string title: Tool Call Id message_id: anyOf: - type: string - type: 'null' title: Message Id check_in_date: type: string title: Check In Date check_out_date: type: string title: Check Out Date adults: anyOf: - type: integer - type: 'null' title: Adults default: 2 children: anyOf: - type: integer - type: 'null' title: Children default: 0 children_ages: anyOf: - type: string - type: 'null' title: Children Ages booking_links: items: $ref: '#/components/schemas/BookingLink' type: array title: Booking Links booking_links_status: type: string title: Booking Links Status default: ready additional_images: items: type: string type: array title: Additional Images additional_images_thumbhashes: items: anyOf: - type: string - type: 'null' type: array title: Additional Images Thumbhashes reviews_breakdown: items: {} type: array title: Reviews Breakdown sample_reviews: items: {} type: array title: Sample Reviews address: anyOf: - type: string - type: 'null' title: Address confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number is_booked: type: boolean title: Is Booked default: false taxes_and_fees: anyOf: - type: number - type: 'null' title: Taxes And Fees is_user_import: type: boolean title: Is User Import default: false source_reference: anyOf: - $ref: '#/components/schemas/SourceReference' - type: 'null' place_id: anyOf: - type: string - type: 'null' title: Place Id type: object required: - name - __index - __tool_call_id - check_in_date - check_out_date title: HotelCardData description: >- Hotel card data for frontend - extends HotelOptionOutput with card metadata. This is the serialization format sent to the frontend HotelCard component. It converts from HotelOptionOutput (cached tool result) plus enrichment data. ImportedRailCardData: properties: departure_datetime: type: string format: date-time title: Departure Datetime arrival_datetime: type: string format: date-time title: Arrival Datetime duration_seconds: type: integer title: Duration Seconds duration_display: type: string title: Duration Display departure_id: type: string title: Departure Id arrival_id: type: string title: Arrival Id train_names: items: type: string type: array title: Train Names num_transfers: type: integer title: Num Transfers default: 0 coach_price: anyOf: - type: number - type: 'null' title: Coach Price currency: type: string title: Currency default: USD travel_legs: items: $ref: '#/components/schemas/ImportedRailLeg' type: array title: Travel Legs booking_date: type: string title: Booking Date booking_links: items: $ref: '#/components/schemas/BookingLink' type: array title: Booking Links confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number is_booked: type: boolean title: Is Booked default: false is_user_import: type: boolean title: Is User Import default: true ground_mode: type: string title: Ground Mode default: rail type: object required: - departure_datetime - arrival_datetime - duration_seconds - duration_display - departure_id - arrival_id - booking_date title: ImportedRailCardData description: |- Flat RailOption-shaped card payload for an imported rail journey. The frontend RailCard component renders the RailOption shape (travel_legs, departure_datetime, …), NOT the nested RailCardData — sending RailCardData hits the component's empty-travel_legs guard and renders nothing. This model is the single typed source of that flat shape; both the chat hydration dict and GET /bookings use it. RoadCardData: properties: operator: anyOf: - type: string - type: 'null' title: Operator pickup_city: anyOf: - type: string - type: 'null' title: Pickup City pickup_address: anyOf: - type: string - type: 'null' title: Pickup Address pickup_datetime: type: string format: date-time title: Pickup Datetime dropoff_city: anyOf: - type: string - type: 'null' title: Dropoff City dropoff_address: anyOf: - type: string - type: 'null' title: Dropoff Address dropoff_datetime: anyOf: - type: string format: date-time - type: 'null' title: Dropoff Datetime duration_minutes: type: integer title: Duration Minutes default: 0 total_price: anyOf: - type: number - type: 'null' title: Total Price currency: type: string title: Currency default: USD passenger_names: items: type: string type: array title: Passenger Names __index: type: integer title: Index __tool_call_id: type: string title: Tool Call Id message_id: anyOf: - type: string - type: 'null' title: Message Id confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number is_booked: type: boolean title: Is Booked default: false is_user_import: type: boolean title: Is User Import default: false type: object required: - pickup_datetime - __index - __tool_call_id title: RoadCardData description: |- Road transport card data for the frontend RoadCard component. Flat single-ride shape: road journeys are always one leg with one RoadSegment (a round trip is two separate journeys). CarRentalCardData: properties: vendor: type: string title: Vendor pickup_location: anyOf: - type: string - type: 'null' title: Pickup Location pickup_city: anyOf: - type: string - type: 'null' title: Pickup City pickup_datetime: type: string format: date-time title: Pickup Datetime dropoff_location: anyOf: - type: string - type: 'null' title: Dropoff Location dropoff_city: anyOf: - type: string - type: 'null' title: Dropoff City dropoff_datetime: anyOf: - type: string format: date-time - type: 'null' title: Dropoff Datetime vehicle_class: anyOf: - type: string - type: 'null' title: Vehicle Class driver_name: anyOf: - type: string - type: 'null' title: Driver Name total_price: anyOf: - type: number - type: 'null' title: Total Price currency: type: string title: Currency default: USD __index: type: integer title: Index __tool_call_id: type: string title: Tool Call Id message_id: anyOf: - type: string - type: 'null' title: Message Id confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number is_booked: type: boolean title: Is Booked default: false is_user_import: type: boolean title: Is User Import default: false type: object required: - vendor - pickup_datetime - __index - __tool_call_id title: CarRentalCardData description: Car rental card data for the frontend CarRentalCard component. AttractionDisplayData: properties: from_email: type: boolean title: From Email default: false gmail_link: anyOf: - type: string - type: 'null' title: Gmail Link import_kind: anyOf: - type: string enum: - email - image - text - type: 'null' title: Import Kind import_link: anyOf: - type: string - type: 'null' title: Import Link import_sources: items: $ref: '#/components/schemas/ImportSource' type: array title: Import Sources id: type: string title: Id name: type: string title: Name place_id: anyOf: - type: string - type: 'null' title: Place Id latitude: anyOf: - type: number - type: 'null' title: Latitude longitude: anyOf: - type: number - type: 'null' title: Longitude thumbnail: anyOf: - type: string - type: 'null' title: Thumbnail thumbnail_thumbhash: anyOf: - type: string - type: 'null' title: Thumbnail Thumbhash rating: anyOf: - type: number - type: 'null' title: Rating num_reviews: anyOf: - type: integer - type: 'null' title: Num Reviews category: anyOf: - type: string - type: 'null' title: Category address: anyOf: - type: string - type: 'null' title: Address city: anyOf: - type: string - type: 'null' title: City state: anyOf: - type: string - type: 'null' title: State country: anyOf: - type: string - type: 'null' title: Country source_reference: anyOf: - $ref: '#/components/schemas/SourceReference' - type: 'null' activity_details: anyOf: - additionalProperties: true type: object - type: 'null' title: Activity Details activity_type: anyOf: - type: string - type: 'null' title: Activity Type start_datetime: anyOf: - type: string - type: 'null' title: Start Datetime end_datetime: anyOf: - type: string - type: 'null' title: End Datetime venue_name: anyOf: - type: string - type: 'null' title: Venue Name seat_info: anyOf: - type: string - type: 'null' title: Seat Info quantity: anyOf: - type: integer - type: 'null' title: Quantity booking_source: anyOf: - type: string - type: 'null' title: Booking Source confirmation_number: anyOf: - type: string - type: 'null' title: Confirmation Number total_price: anyOf: - type: number - type: 'null' title: Total Price currency: anyOf: - type: string - type: 'null' title: Currency is_booked: type: boolean title: Is Booked default: false type: object required: - id - name title: AttractionDisplayData description: Pre-formatted attraction data for AttractionCard component. JourneyDisplay: properties: direction: anyOf: - type: string enum: - outbound - return - type: 'null' title: Direction segments: items: $ref: '#/components/schemas/SegmentDisplay' type: array title: Segments total_duration_in_minutes: type: integer title: Total Duration In Minutes departure_date: anyOf: - type: string format: date-time - type: 'null' title: Departure Date arrival_date: anyOf: - type: string format: date-time - type: 'null' title: Arrival Date type: object required: - segments - total_duration_in_minutes title: JourneyDisplay description: Frontend format for a journey leg. CashDisplay: properties: type: type: string const: cash title: Type default: cash price: anyOf: - type: number - type: 'null' title: Price currency: type: string title: Currency default: USD type: object title: CashDisplay description: Frontend format for cash pricing. BookingLink: properties: link: type: string title: Link label: type: string title: Label price: anyOf: - type: number - type: 'null' title: Price currency: anyOf: - type: string - type: 'null' title: Currency primary: type: boolean title: Primary default: false fare_name: anyOf: - type: string - type: 'null' title: Fare Name free_carry_on: anyOf: - type: integer - type: 'null' title: Free Carry On free_checked_bags: anyOf: - type: integer - type: 'null' title: Free Checked Bags type: object required: - link - label title: BookingLink description: A booking link with optional pricing and baggage info. ExtractedFlightSegment: properties: departure_airport: type: string title: Departure Airport description: 3-letter IATA code (e.g., 'SFO') arrival_airport: type: string title: Arrival Airport description: 3-letter IATA code (e.g., 'JFK') departure_datetime: type: string format: date-time title: Departure Datetime description: Departure date and time (local time, no timezone) arrival_datetime: anyOf: - type: string format: date-time - type: 'null' title: Arrival Datetime description: Arrival date and time (local time, no timezone) duration_minutes: anyOf: - type: integer - type: 'null' title: Duration Minutes description: Flight duration in minutes if mentioned (e.g., '16h 35m' = 995) flight_number: anyOf: - type: string - type: 'null' title: Flight Number description: Flight number (e.g., 'UA123') airline: anyOf: - type: string - type: 'null' title: Airline description: Airline name cabin_class: anyOf: - type: string - type: 'null' title: Cabin Class description: >- Cabin class (e.g., 'Economy', 'Premium Economy', 'Business', 'First') seat: anyOf: - type: string - type: 'null' title: Seat description: Seat assignment if shown (e.g., '14A', '2K') aircraft_type_iata: anyOf: - type: string - type: 'null' title: Aircraft Type Iata description: IATA aircraft type code (e.g., '77W', '320') aircraft_type_icao: anyOf: - type: string - type: 'null' title: Aircraft Type Icao description: ICAO aircraft type code (e.g., 'B77W', 'A320') tail_number: anyOf: - type: string - type: 'null' title: Tail Number description: Aircraft registration number (e.g., 'N12345') departure_terminal: anyOf: - type: string - type: 'null' title: Departure Terminal description: Departure terminal (e.g., 'T1', 'B') arrival_terminal: anyOf: - type: string - type: 'null' title: Arrival Terminal description: Arrival terminal departure_country: anyOf: - type: string - type: 'null' title: Departure Country description: Departure country ISO code (e.g., 'US') arrival_country: anyOf: - type: string - type: 'null' title: Arrival Country description: Arrival country ISO code (e.g., 'GB') distance_km: anyOf: - type: number - type: 'null' title: Distance Km description: Great-circle distance in kilometers number_of_stops: anyOf: - type: integer - type: 'null' title: Number Of Stops description: Number of intermediate stops (0 for non-stop) flight_state: anyOf: - type: string - type: 'null' title: Flight State description: Flight state from OAG (e.g., 'Scheduled', 'InGate', 'Cancelled') pre_oag_departure_datetime: anyOf: - type: string format: date-time - type: 'null' title: Pre Oag Departure Datetime description: >- The ticket's own departure time, recorded the first time OAG touches this segment and never overwritten — the recovery value if an enrichment adjusts wrongly. pre_oag_arrival_datetime: anyOf: - type: string format: date-time - type: 'null' title: Pre Oag Arrival Datetime description: The ticket's own arrival time; see pre_oag_departure_datetime. departure_datetime_utc: anyOf: - type: string format: date-time - type: 'null' title: Departure Datetime Utc description: >- Authoritative departure instant from OAG, timezone-aware UTC. The naive departure_datetime stays local wall-clock at the airport. arrival_datetime_utc: anyOf: - type: string format: date-time - type: 'null' title: Arrival Datetime Utc description: >- Authoritative arrival instant from OAG, timezone-aware UTC. The naive arrival_datetime stays local wall-clock at the airport. type: object required: - departure_airport - arrival_airport - departure_datetime title: ExtractedFlightSegment description: Single flight leg extracted from user message. AwardPayment: properties: amount: anyOf: - type: integer - type: 'null' title: Amount description: Number of miles/points used (e.g., 800, 25000) unit: type: string enum: - miles - points title: Unit description: '''miles'' or ''points''' account: anyOf: - type: string - type: 'null' title: Account description: >- Loyalty account identifier if shown (e.g., 'MileagePlus XXXXX205', 'Bonvoy XXXX1234') type: object required: - unit title: AwardPayment description: Payment made with loyalty miles/points. RoomOption: properties: offer_id: type: string title: Offer Id room_name: type: string title: Room Name mapped_room_id: anyOf: - type: integer - type: 'null' title: Mapped Room Id bed_summary: anyOf: - type: string - type: 'null' title: Bed Summary size_sqft: anyOf: - type: integer - type: 'null' title: Size Sqft max_occupancy: anyOf: - type: integer - type: 'null' title: Max Occupancy board_type: anyOf: - type: string - type: 'null' title: Board Type board_name: anyOf: - type: string - type: 'null' title: Board Name refundable: type: boolean title: Refundable default: false cancel_until: anyOf: - type: string - type: 'null' title: Cancel Until price_per_night: anyOf: - type: number - type: 'null' title: Price Per Night total_price: anyOf: - type: number - type: 'null' title: Total Price initial_price: anyOf: - type: number - type: 'null' title: Initial Price taxes_included: anyOf: - type: boolean - type: 'null' title: Taxes Included currency: type: string title: Currency default: USD photos: items: type: string type: array title: Photos amenities: items: type: string type: array title: Amenities why: anyOf: - type: string - type: 'null' title: Why type: object required: - offer_id - room_name title: RoomOption description: >- A single bookable room-rate option for a hotel (Nuitee LiteAPI). `total_price` and `price_per_night` are ALL-IN — `retailRate.total` plus LiteAPI's mandatory excluded fees. No field here holds the pre-fee number, deliberately: it is not a price anyone may be shown. The static-content fields (`bed_summary`/`size_sqft`/`photos`/`amenities`) come from the `/data/hotel` room join at hydration time and are empty at search time. SourceReference: properties: tool_call_id: type: string title: Tool Call Id result_index: type: integer title: Result Index source: type: string enum: - api - user_import - user_manual - user_booking title: Source default: api type: object required: - tool_call_id - result_index title: SourceReference description: >- Reference to a cached tool result for tracking itinerary item sources. ``source`` distinguishes provenance: ``api`` (an AI/tool search result), ``user_import`` (parsed from the user's email — renders a "From email" badge and the imageless cost-breakdown card), ``user_manual`` (added by hand via the "Add stay" form — a normal image-carrying card, no badge), and ``user_booking``. ``user_booking`` is deliberately NOT ``user_import``: the item did not come from the user's inbox, and a "From email" badge on a booking we took money for would be a lie. Frontends branch only on ``user_import``, so the new value falls through to the ordinary card. ImportedRailLeg: properties: train_id: type: string title: Train Id route: type: string title: Route default: '' departure_id: type: string title: Departure Id arrival_id: type: string title: Arrival Id departure_time: type: string title: Departure Time arrival_time: type: string title: Arrival Time duration: type: string title: Duration operator_logo: anyOf: - type: string - type: 'null' title: Operator Logo type: object required: - train_id - departure_id - arrival_id - departure_time - arrival_time - duration title: ImportedRailLeg description: |- One travel leg of an imported rail journey, in the flat RailOption shape the frontend RailCard renders (times as HH:MM strings). SegmentDisplay: properties: kind: type: string const: flight title: Kind default: flight type: anyOf: - type: string enum: - outbound - return - type: 'null' title: Type departure: $ref: '#/components/schemas/DepartureArrivalDisplay' arrival: $ref: '#/components/schemas/DepartureArrivalDisplay' length_in_minutes: type: integer title: Length In Minutes flight_number: type: string title: Flight Number airline: type: string title: Airline airline_logo: anyOf: - type: string - type: 'null' title: Airline Logo aircraft: anyOf: - type: string - type: 'null' title: Aircraft travel_class: anyOf: - type: string - type: 'null' title: Travel Class starlink_verdict: anyOf: - type: string enum: - 'yes' - probably_yes - probably_no - 'no' - type: 'null' title: Starlink Verdict starlink_reasoning: anyOf: - type: string - type: 'null' title: Starlink Reasoning type: object required: - departure - arrival - length_in_minutes - flight_number - airline title: SegmentDisplay description: Frontend format for a flight segment. DepartureArrivalDisplay: properties: time: type: string format: date-time title: Time airport: type: string title: Airport timezone: anyOf: - type: string - type: 'null' title: Timezone latitude: anyOf: - type: number - type: 'null' title: Latitude longitude: anyOf: - type: number - type: 'null' title: Longitude type: object required: - time - airport title: DepartureArrivalDisplay description: >- Frontend format for departure/arrival points. `timezone` (IANA) and the coordinates come from the airport catalog when the journey endpoint itself has none, so a consumer can compute the offset crossed and the direction flown without its own airport table. ````