{"openapi":"3.1.0","info":{"title":"OpenPAX Public API","version":"1.2.0","description":"Agent-native flight booking API. Search flights and book tickets with two API calls. Manage bookings, select seats, add ancillaries, and hunt deals. No authentication required.","contact":{"name":"OpenPAX","url":"https://openpax.ai","email":"info@openpax.ai"}},"servers":[{"url":"https://api.openpax.ai","description":"Production"}],"paths":{"/v1/public/search":{"post":{"operationId":"searchFlights","summary":"Search for flights","description":"Search for flights using natural language or structured parameters. Supports NLP queries (e.g. 'Vienna to London next Tuesday'), structured IATA-based search, and multi-city itineraries.","tags":["Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Search request — use 'query' for NLP mode, OR 'origin'+'destination'+'departure_date' for structured, OR 'type: multi_city' + 'slices[]' for multi-city.","properties":{"query":{"type":"string","description":"Natural language search (e.g. 'Vienna to London next Tuesday, economy'). Use this OR structured fields, not both."},"type":{"type":"string","enum":["multi_city"],"description":"Set to 'multi_city' for multi-city searches. Requires 'slices' array."},"origin":{"type":"string","pattern":"^[A-Z]{3}$","description":"3-letter IATA departure code (e.g. VIE)"},"destination":{"type":"string","pattern":"^[A-Z]{3}$","description":"3-letter IATA arrival code (e.g. LHR)"},"departure_date":{"type":"string","format":"date","description":"Departure date (YYYY-MM-DD)"},"return_date":{"type":"string","format":"date","description":"Return date for round trips (YYYY-MM-DD)"},"slices":{"type":"array","description":"Multi-city legs — required when type=multi_city","items":{"type":"object","required":["origin","destination","departure_date"],"properties":{"origin":{"type":"string","pattern":"^[A-Z]{3}$"},"destination":{"type":"string","pattern":"^[A-Z]{3}$"},"departure_date":{"type":"string","format":"date"}}}},"passengers":{"description":"Passenger list. Adult: {type:'adult'}. Child 2-11: {age:N} (NO type field). Infant: {type:'infant_without_seat'}.","oneOf":[{"type":"integer","minimum":1,"maximum":9,"description":"Number of adults (shorthand)"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["adult","infant_without_seat"]},"age":{"type":"integer","minimum":2,"maximum":11,"description":"Child age — use INSTEAD of type"}}}}]},"cabin_class":{"type":"string","enum":["economy","premium_economy","business","first"],"default":"economy"},"options":{"$ref":"#/components/schemas/SearchOptions"}}},"examples":{"nlp":{"summary":"Natural language search","value":{"query":"Vienna to London next Tuesday, economy"}},"structured":{"summary":"Structured search (one-way)","value":{"origin":"VIE","destination":"LHR","departure_date":"2026-03-10","passengers":1,"cabin_class":"economy"}},"roundTrip":{"summary":"Round trip with mixed passengers","value":{"origin":"VIE","destination":"BCN","departure_date":"2026-06-15","return_date":"2026-06-22","passengers":[{"type":"adult"},{"type":"adult"},{"age":8},{"type":"infant_without_seat"}],"cabin_class":"economy"}},"multiCity":{"summary":"Multi-city itinerary","value":{"type":"multi_city","slices":[{"origin":"VIE","destination":"LHR","departure_date":"2026-04-01"},{"origin":"LHR","destination":"JFK","departure_date":"2026-04-05"},{"origin":"JFK","destination":"VIE","departure_date":"2026-04-12"}],"passengers":[{"type":"adult"}],"cabin_class":"economy"}}}}}},"responses":{"200":{"description":"Flight search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (20 requests/minute per IP)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/book":{"post":{"operationId":"bookFlight","summary":"Book a flight","description":"Initiate a booking for a flight offer. Returns a payment link that the passenger uses to complete payment. After payment, the ticket is automatically issued and a confirmation email is sent. The response includes a short payment link (openpax.ai/pay/REF) suitable for sharing.","tags":["Booking"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookRequest"},"examples":{"singleAdult":{"summary":"Single adult passenger","value":{"offer_id":"off_dfl_abc123","email":"traveler@example.com","passengers":[{"first_name":"Max","last_name":"Mustermann","date_of_birth":"1990-05-15","email":"max@example.com","phone":"+43664123456"}]}},"familyWithChild":{"summary":"Family with child and infant","value":{"offer_id":"off_dfl_abc123","email":"family@example.com","passengers":[{"first_name":"Max","last_name":"Mustermann","date_of_birth":"1990-05-15","email":"max@example.com","phone":"+43664123456","type":"adult"},{"first_name":"Anna","last_name":"Mustermann","date_of_birth":"2018-03-22","email":"max@example.com","phone":"+43664123456"},{"first_name":"Baby","last_name":"Mustermann","date_of_birth":"2025-01-10","email":"max@example.com","phone":"+43664123456","type":"infant_without_seat"}]}}}}}},"responses":{"201":{"description":"Booking initiated — payment link returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/bookings/lookup":{"post":{"operationId":"lookupBooking","summary":"Look up a booking","description":"Retrieve booking details using the booking reference and passenger last name for verification.","tags":["Booking Management"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["booking_reference","last_name"],"properties":{"booking_reference":{"type":"string","description":"The booking reference code (e.g. OPAX-ABC123)"},"last_name":{"type":"string","description":"Last name of any passenger on the booking (for verification)"}}},"examples":{"lookup":{"summary":"Look up booking","value":{"booking_reference":"OPAX-ABC123","last_name":"Mustermann"}}}}}},"responses":{"200":{"description":"Booking details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingDetailResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Booking not found or last name mismatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/bookings/cancel":{"post":{"operationId":"cancelBooking","summary":"Cancel a booking","description":"Cancel a booking. If the booking is confirmed, attempts to cancel with the airline and issue a Stripe refund. Non-refundable fares may result in a zero refund.","tags":["Booking Management"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["booking_id","last_name"],"properties":{"booking_id":{"type":"string","description":"Booking ID (UUID)"},"last_name":{"type":"string","description":"Last name of a passenger (for verification)"}}},"examples":{"cancel":{"summary":"Cancel a booking","value":{"booking_id":"550e8400-e29b-41d4-a716-446655440000","last_name":"Mustermann"}}}}}},"responses":{"200":{"description":"Booking cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancellationResponse"}}}},"400":{"description":"Cannot cancel booking in current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Booking not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/bookings/change-options":{"post":{"operationId":"getChangeOptions","summary":"Get flight change options","description":"Get available change options for a confirmed booking. Returns alternative flights with price differences. Only works for confirmed bookings with an active airline order.","tags":["Booking Management"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["booking_id","last_name","new_departure_date"],"properties":{"booking_id":{"type":"string","description":"Booking ID"},"last_name":{"type":"string","description":"Last name of a passenger (for verification)"},"new_departure_date":{"type":"string","format":"date","description":"Desired new departure date (YYYY-MM-DD)"}}},"examples":{"changeOptions":{"summary":"Get change options","value":{"booking_id":"550e8400-e29b-41d4-a716-446655440000","last_name":"Mustermann","new_departure_date":"2026-03-15"}}}}}},"responses":{"200":{"description":"Available change offers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeOptionsResponse"}}}},"400":{"description":"Booking cannot be changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Booking not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/bookings/confirm-change":{"post":{"operationId":"confirmChange","summary":"Confirm a flight change","description":"Confirm a selected change offer to modify the booking. The change is applied immediately and flight data is updated.","tags":["Booking Management"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["booking_id","last_name","change_offer_id"],"properties":{"booking_id":{"type":"string","description":"Booking ID"},"last_name":{"type":"string","description":"Last name of a passenger (for verification)"},"change_offer_id":{"type":"string","description":"Change offer ID from the change-options response"}}},"examples":{"confirmChange":{"summary":"Confirm flight change","value":{"booking_id":"550e8400-e29b-41d4-a716-446655440000","last_name":"Mustermann","change_offer_id":"oco_abc123"}}}}}},"responses":{"200":{"description":"Change confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingChangeResponse"}}}},"400":{"description":"Cannot change booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Booking not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/bookings/{id}":{"get":{"operationId":"getBooking","summary":"Get booking by ID","description":"Retrieve full booking details by booking ID (UUID). No last_name verification required.","tags":["Booking Management"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Booking UUID"}],"responses":{"200":{"description":"Booking details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingDetailResponse"}}}},"404":{"description":"Booking not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/bookings/{id}/seat-maps":{"post":{"operationId":"getSeatMaps","summary":"Get seat maps for a booking","description":"Retrieve available seat maps for all segments of a booking. Returns rows, seats, availability, types, and prices.","tags":["Seats"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Booking UUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["last_name"],"properties":{"last_name":{"type":"string","description":"Last name of a passenger (for verification)"}}}}}},"responses":{"200":{"description":"Seat maps for all segments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeatMapResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Booking not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/bookings/{id}/seats":{"post":{"operationId":"selectSeats","summary":"Select seats for a booking","description":"Select specific seats for passengers. Requires seat_service_id from the seat map response.","tags":["Seats"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Booking UUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["last_name","selections"],"properties":{"last_name":{"type":"string"},"selections":{"type":"array","minItems":1,"maxItems":36,"items":{"type":"object","required":["passenger_index","segment_id","seat_service_id"],"properties":{"passenger_index":{"type":"integer","minimum":0},"segment_id":{"type":"string"},"seat_service_id":{"type":"string"}}}}}},"examples":{"selectSeats":{"summary":"Select seats for 2 passengers","value":{"last_name":"Mustermann","selections":[{"passenger_index":0,"segment_id":"seg_abc","seat_service_id":"srv_12A"},{"passenger_index":1,"segment_id":"seg_abc","seat_service_id":"srv_12B"}]}}}}}},"responses":{"200":{"description":"Seats selected","content":{"application/json":{"schema":{"type":"object","properties":{"booking_id":{"type":"string"},"seat_selections":{"type":"array","items":{"type":"object","properties":{"passenger_index":{"type":"integer"},"segment_id":{"type":"string"},"designator":{"type":"string"},"price_amount":{"type":"string"},"price_currency":{"type":"string"}}}}}}}}},"400":{"description":"Invalid selection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/bookings/{id}/changes":{"post":{"operationId":"getAirlineChanges","summary":"Get airline-initiated changes","description":"Check for airline-initiated schedule changes on a booking.","tags":["Airline Changes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["last_name"],"properties":{"last_name":{"type":"string"}}}}}},"responses":{"200":{"description":"Airline-initiated changes","content":{"application/json":{"schema":{"type":"object","properties":{"booking_id":{"type":"string"},"changes":{"type":"array","items":{"type":"object","properties":{"change_id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"404":{"description":"Booking not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/bookings/{id}/changes/{changeId}/accept":{"post":{"operationId":"acceptAirlineChange","summary":"Accept an airline-initiated change","description":"Accept a pending airline-initiated schedule change.","tags":["Airline Changes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"changeId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["last_name"],"properties":{"last_name":{"type":"string"}}}}}},"responses":{"200":{"description":"Change accepted","content":{"application/json":{"schema":{"type":"object","properties":{"booking_id":{"type":"string"},"change_id":{"type":"string"},"status":{"type":"string","example":"accepted"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/bookings/{id}/ancillaries/available":{"post":{"operationId":"getAvailableAncillaries","summary":"Get available ancillaries","description":"List available ancillary services for a booking — checked bags, carry-on, meals, lounge, priority boarding, fast track.","tags":["Ancillaries"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["last_name"],"properties":{"last_name":{"type":"string"}}}}}},"responses":{"200":{"description":"Available ancillary services","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AncillaryResponse"}}}},"404":{"description":"Booking not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/bookings/{id}/ancillaries":{"post":{"operationId":"selectAncillaries","summary":"Select ancillaries for a booking","description":"Add ancillary services (bags, meals, etc.) to a booking.","tags":["Ancillaries"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["last_name","selections"],"properties":{"last_name":{"type":"string"},"selections":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["service_id","passenger_index"],"properties":{"service_id":{"type":"string"},"passenger_index":{"type":"integer","minimum":0},"segment_id":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":10,"default":1}}}}}},"examples":{"addBag":{"summary":"Add checked bag","value":{"last_name":"Mustermann","selections":[{"service_id":"srv_bag_23kg","passenger_index":0,"quantity":1}]}}}}}},"responses":{"200":{"description":"Ancillaries added","content":{"application/json":{"schema":{"type":"object","properties":{"booking_id":{"type":"string"},"added_services":{"type":"array","items":{"type":"object"}},"new_total_amount":{"type":"string"},"new_total_currency":{"type":"string"}}}}}},"400":{"description":"Invalid selection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/public/booking/action":{"get":{"operationId":"bookingAction","summary":"Handle booking action from email","description":"Handles JWT-based action tokens from email buttons (accept change, cancel, rebook). Redirects to the appropriate UI page.","tags":["Utilities"],"parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"},"description":"JWT action token"}],"responses":{"302":{"description":"Redirects to action result page"}}}},"/v1/public/pay/{ref}":{"get":{"operationId":"shortPaymentLink","summary":"Short payment link redirect","description":"Redirects to the Stripe payment page. Already-paid bookings redirect to booking detail. Format: openpax.ai/pay/OPAX-AB1C","tags":["Utilities"],"parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"},"description":"Short booking reference"}],"responses":{"302":{"description":"Redirects to Stripe checkout or booking detail"}}}},"/v1/public/deals/hunt":{"post":{"operationId":"huntDeals","summary":"Hunt for flight deals","description":"Search for cheapest flights across multiple routes and a date range. Max 5 routes, max 5-day date window.","tags":["Deals"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HuntDealsRequest"},"examples":{"huntDeals":{"summary":"Hunt deals from Vienna","value":{"routes":[{"origin":"VIE","destination":"BCN"},{"origin":"VIE","destination":"LIS"},{"origin":"VIE","destination":"ATH"}],"departure_date_from":"2026-06-01","departure_date_to":"2026-06-05","cabin_class":"economy","max_price_eur":200,"passengers":1,"nonstop_only":false}}}}}},"responses":{"200":{"description":"Deal results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HuntDealsResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"NlpSearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":3,"maxLength":500,"description":"Natural language flight search query"},"options":{"$ref":"#/components/schemas/SearchOptions"}}},"StructuredSearchRequest":{"type":"object","required":["origin","destination","departure_date"],"properties":{"origin":{"type":"string","pattern":"^[A-Z]{3}$","description":"3-letter IATA airport code for departure"},"destination":{"type":"string","pattern":"^[A-Z]{3}$","description":"3-letter IATA airport code for arrival"},"departure_date":{"type":"string","format":"date"},"return_date":{"type":"string","format":"date"},"passengers":{"oneOf":[{"type":"integer","minimum":1,"maximum":9,"default":1},{"type":"array","minItems":1,"maxItems":9,"items":{"type":"object","properties":{"type":{"type":"string","enum":["adult","infant_without_seat"]},"age":{"type":"integer","minimum":2,"maximum":11,"description":"Child age (2-11), use INSTEAD of type"}}}}]},"cabin_class":{"type":"string","enum":["economy","premium_economy","business","first"],"default":"economy"},"options":{"$ref":"#/components/schemas/SearchOptions"}}},"MultiCitySearchRequest":{"type":"object","required":["type","slices","passengers"],"properties":{"type":{"type":"string","enum":["multi_city"]},"slices":{"type":"array","minItems":2,"maxItems":6,"items":{"type":"object","required":["origin","destination","departure_date"],"properties":{"origin":{"type":"string","pattern":"^[A-Z]{3}$"},"destination":{"type":"string","pattern":"^[A-Z]{3}$"},"departure_date":{"type":"string","format":"date"}}}},"passengers":{"type":"array","minItems":1,"maxItems":9,"items":{"type":"object","properties":{"type":{"type":"string","enum":["adult","infant_without_seat"]},"age":{"type":"integer","minimum":2,"maximum":11}}}},"cabin_class":{"type":"string","enum":["economy","premium_economy","business","first"],"default":"economy"},"options":{"$ref":"#/components/schemas/SearchOptions"}}},"SearchOptions":{"type":"object","properties":{"max_results":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Max number of offers to return"},"max_price_eur":{"type":"number","description":"Filter offers above this price"},"max_stops":{"type":"integer","minimum":0,"maximum":3,"description":"Max number of stops. Use 0 for direct/non-stop flights only."},"source_types":{"type":"array","items":{"type":"string","enum":["ndc","gds"]},"description":"Filter offers by source type"},"preferred_departure_time_of_day":{"type":"string","enum":["morning","afternoon","evening","night"],"description":"Filter outbound by departure time: morning=06-12, afternoon=12-17, evening=17-22, night=22-06"},"preferred_return_time_of_day":{"type":"string","enum":["morning","afternoon","evening","night"],"description":"Filter return leg by departure time (round-trip only)"},"allow_mixed_airlines":{"type":"boolean","default":true,"description":"Allow round-trips combining different airlines (e.g. Aegean out + Austrian return)."},"airline_iata_codes":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","pattern":"^[A-Z0-9]{2}$"},"description":"Hard include list of airline IATA codes, e.g. [\"OS\", \"LH\"]"},"offset":{"type":"integer","default":0,"description":"Pagination offset — increase by max_results to get next page"}}},"SearchResponse":{"type":"object","properties":{"search_id":{"type":"string","description":"Unique search identifier (srch_ prefix)"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/FlightOffer"}},"currency":{"type":"string","example":"EUR"},"source_breakdown":{"type":"object","properties":{"ndc_count":{"type":"integer"},"gds_count":{"type":"integer"},"ndc_avg_price":{"type":"number","nullable":true},"gds_avg_price":{"type":"number","nullable":true}}},"total_available":{"type":"integer","description":"Total offers before pagination (deprecated, use total_count)"},"total_count":{"type":"integer","description":"Total offers matching the search before pagination"},"has_more":{"type":"boolean","description":"Whether more results are available beyond the current page"}}},"FlightOffer":{"type":"object","properties":{"offer_id":{"type":"string","description":"Unique offer ID — use this to book"},"type":{"type":"string","enum":["one_way","round_trip","multi_city"]},"airline":{"type":"string","description":"Full airline name with IATA code, e.g. 'Austrian (OS)', 'Lufthansa (LH)', 'Condor (DE)'. Use EXACTLY this string for display."},"airline_code":{"type":"string","description":"IATA code only — DO NOT use for display, use airline field instead."},"flight_number":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"},"departure_at":{"type":"string","format":"date-time"},"arrival_at":{"type":"string","format":"date-time"},"duration_minutes":{"type":"integer"},"stops":{"type":"integer"},"cabin_class":{"type":"string"},"price_eur":{"type":"number","description":"Ticket price in EUR (without service fee)"},"total_with_fee_eur":{"type":"number","description":"Total all-inclusive price in EUR including service fee — ALWAYS show this to users, never price_eur alone"},"is_split_booking":{"type":"boolean","description":"True if outbound and return are separate tickets from different airlines"},"return_flight":{"type":"object","nullable":true,"description":"Return flight details for round-trip offers","properties":{"airline":{"type":"string","description":"Full return airline name, e.g. 'Austrian'"},"airline_code":{"type":"string"},"flight_number":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"},"departure_at":{"type":"string","format":"date-time","description":"Return departure time (local)"},"arrival_at":{"type":"string","format":"date-time","description":"Return arrival time (local)"},"duration_minutes":{"type":"integer"},"stops":{"type":"integer"}}},"score":{"type":"integer","description":"Quality score 0-100"},"expires_at":{"type":"string","format":"date-time"},"fare_brand_name":{"type":"string","nullable":true},"fare_basis_code":{"type":"string","nullable":true},"cabin_class_marketing_name":{"type":"string","nullable":true},"ngs_shelf":{"type":"integer","nullable":true},"fare_conditions":{"type":"object","nullable":true,"properties":{"changeable":{"type":"boolean"},"change_penalty_amount":{"type":"string","nullable":true},"refundable":{"type":"boolean"},"refund_penalty_amount":{"type":"string","nullable":true}}},"fare_benefits":{"type":"object","nullable":true,"properties":{"advance_seat_selection":{"type":"boolean"},"priority_boarding":{"type":"boolean"},"priority_check_in":{"type":"boolean"}}},"baggage":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["carry_on","checked"]},"quantity":{"type":"integer"}}}},"slices":{"type":"array","items":{"type":"object","properties":{"flight_number":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"},"departure_at":{"type":"string","format":"date-time"},"arrival_at":{"type":"string","format":"date-time"},"duration_minutes":{"type":"integer"},"stops":{"type":"integer"},"airline":{"type":"string"},"airline_code":{"type":"string"}}}},"identity_documents_required":{"type":"boolean"},"supported_loyalty_programmes":{"type":"array","items":{"type":"string"}},"total_emissions_kg":{"type":"string","nullable":true}}},"BookRequest":{"type":"object","required":["offer_id","email","passengers"],"properties":{"offer_id":{"type":"string","description":"Offer ID from search results (off_dfl_ prefix)"},"email":{"type":"string","format":"email","description":"Contact email"},"passengers":{"type":"array","minItems":1,"maxItems":9,"items":{"$ref":"#/components/schemas/PassengerBooking"}},"source_agent":{"type":"string","maxLength":50}}},"PassengerBooking":{"type":"object","required":["first_name","last_name","date_of_birth","email","phone"],"description":"Passenger details. Adults: type='adult'. Children 2-11: omit type, age inferred from date_of_birth. Infants: type='infant_without_seat'.","properties":{"first_name":{"type":"string","minLength":1,"maxLength":100},"last_name":{"type":"string","minLength":1,"maxLength":100},"date_of_birth":{"type":"string","format":"date"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"type":{"type":"string","enum":["adult","child","infant_without_seat"]},"title":{"type":"string","enum":["mr","ms","mrs","miss","dr"]},"gender":{"type":"string","enum":["m","f"]},"identity_document":{"type":"object","properties":{"type":{"type":"string","enum":["passport"]},"unique_identifier":{"type":"string"},"issuing_country_code":{"type":"string"},"expires_on":{"type":"string","format":"date"},"nationality":{"type":"string"}},"required":["type","unique_identifier","issuing_country_code","expires_on","nationality"]}}},"Passenger":{"type":"object","deprecated":true,"required":["first_name","last_name","date_of_birth","email","phone"],"properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"date_of_birth":{"type":"string","format":"date"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}},"BookResponse":{"type":"object","properties":{"booking_id":{"type":"string"},"short_ref":{"type":"string","description":"Short booking reference (e.g. OPAX-AB1C)"},"payment_link":{"type":"string","format":"uri","description":"Stripe checkout URL"},"short_payment_link":{"type":"string","format":"uri","description":"Short payment link (e.g. openpax.ai/pay/OPAX-AB1C)"},"email_sent_to":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}},"BookingDetailResponse":{"type":"object","properties":{"booking_id":{"type":"string"},"status":{"type":"string","enum":["pending_payment","payment_received","confirmed","cancelled","expired","failed"]},"booking_reference":{"type":"string"},"flight":{"type":"object","properties":{"origin":{"type":"string"},"destination":{"type":"string"},"airline":{"type":"string"},"airline_code":{"type":"string"},"flight_number":{"type":"string"},"departure_at":{"type":"string","format":"date-time"},"arrival_at":{"type":"string","format":"date-time"},"fare_brand_name":{"type":"string","nullable":true},"cabin_class":{"type":"string","nullable":true},"baggage":{"type":"array","nullable":true,"items":{"type":"object","properties":{"type":{"type":"string","enum":["carry_on","checked"]},"quantity":{"type":"integer"}}}},"identity_documents_required":{"type":"boolean"},"supported_loyalty_programmes":{"type":"array","items":{"type":"string"}}}},"return_flight":{"type":"object","nullable":true},"slices":{"type":"array","nullable":true,"items":{"type":"object","properties":{"flight_number":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"},"departure_at":{"type":"string","format":"date-time"},"arrival_at":{"type":"string","format":"date-time"},"duration_minutes":{"type":"integer"},"stops":{"type":"integer"},"airline":{"type":"string"}}}},"passenger_name":{"type":"string"},"amount_eur":{"type":"number"},"fee_eur":{"type":"number"},"confirmed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"seat_selections":{"type":"array","nullable":true,"items":{"type":"object","properties":{"passenger_index":{"type":"integer"},"segment_id":{"type":"string"},"designator":{"type":"string"}}}}}},"CancellationResponse":{"type":"object","properties":{"booking_id":{"type":"string"},"status":{"type":"string","example":"cancelled"},"refund_amount_eur":{"type":"number"},"refund_policy":{"type":"string","enum":["refunded","non-refundable"]},"cancelled_at":{"type":"string","format":"date-time"}}},"ChangeOptionsResponse":{"type":"object","properties":{"booking_id":{"type":"string"},"current_flight":{"type":"object","properties":{"origin":{"type":"string"},"destination":{"type":"string"},"departure_at":{"type":"string"}}},"change_offers":{"type":"array","items":{"type":"object","properties":{"change_offer_id":{"type":"string"},"price_difference_amount":{"type":"string"},"price_difference_currency":{"type":"string"},"new_total_amount":{"type":"string"},"new_total_currency":{"type":"string"},"refund_to":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time"},"new_flight":{"type":"object","nullable":true,"properties":{"airline":{"type":"string"},"flight_number":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"},"departure_at":{"type":"string"},"arrival_at":{"type":"string"}}}}}}}},"BookingChangeResponse":{"type":"object","properties":{"booking_id":{"type":"string"},"status":{"type":"string","example":"changed"},"message":{"type":"string"}}},"SeatMapResponse":{"type":"object","properties":{"booking_id":{"type":"string"},"segments":{"type":"array","items":{"type":"object","properties":{"segment_id":{"type":"string"},"aircraft":{"type":"string"},"origin":{"type":"string"},"destination":{"type":"string"},"departing_at":{"type":"string"},"rows":{"type":"array","items":{"type":"object","properties":{"number":{"type":"integer"},"seats":{"type":"array","items":{"type":"object","properties":{"designator":{"type":"string"},"available":{"type":"boolean"},"type":{"type":"string","enum":["window","middle","aisle","extra_legroom","other"]},"price_amount":{"type":"string","nullable":true},"price_currency":{"type":"string","nullable":true},"service_id":{"type":"string","nullable":true},"disclosures":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"AncillaryResponse":{"type":"object","properties":{"booking_id":{"type":"string"},"available_services":{"type":"array","items":{"type":"object","properties":{"service_id":{"type":"string"},"type":{"type":"string","enum":["checked_bag","carry_on","meal","lounge","priority_boarding","fast_track","baggage","cancel_for_any_reason"]},"description":{"type":"string"},"price_amount":{"type":"string"},"price_currency":{"type":"string"},"maximum_quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}},"HuntDealsRequest":{"type":"object","required":["routes","departure_date_from","departure_date_to"],"properties":{"routes":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"object","required":["origin","destination"],"properties":{"origin":{"type":"string","pattern":"^[A-Z]{3}$"},"destination":{"type":"string","pattern":"^[A-Z]{3}$"}}}},"departure_date_from":{"type":"string","format":"date"},"departure_date_to":{"type":"string","format":"date"},"cabin_class":{"type":"string","enum":["economy","premium_economy","business","first"],"default":"economy"},"max_price_eur":{"type":"number"},"passengers":{"type":"integer","minimum":1,"maximum":9,"default":1},"nonstop_only":{"type":"boolean","default":false}}},"HuntDealsResponse":{"type":"object","properties":{"deals":{"type":"array","items":{"type":"object","properties":{"route":{"type":"object","properties":{"origin":{"type":"string"},"destination":{"type":"string"}}},"departure_date":{"type":"string","format":"date"},"best_offer":{"$ref":"#/components/schemas/FlightOffer"}}}},"searched_routes":{"type":"integer"},"searched_dates":{"type":"integer"},"total_offers_found":{"type":"integer"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}}}}}},"tags":[{"name":"Search","description":"Flight search"},{"name":"Booking","description":"Create bookings"},{"name":"Booking Management","description":"Lookup, cancel, change bookings"},{"name":"Seats","description":"Seat maps and selection"},{"name":"Ancillaries","description":"Extra services"},{"name":"Airline Changes","description":"Airline-initiated changes"},{"name":"Deals","description":"Deal hunting"},{"name":"Utilities","description":"Payment links, email actions"}],"x-rate-limit":{"requests":20,"window":"1 minute","scope":"per IP address"}}