{"openapi":"3.1.0","info":{"title":"1800airfare Flights API","version":"1.0.0","description":"Flight search, fare-range, and callback-request tools for AI agents. Pricing is ranges-only — book by phone (no live quotable per-trip fares)."},"components":{"schemas":{}},"paths":{"/api/flights/search":{"get":{"operationId":"searchFlights","summary":"Search flights and return the best baggage-included option.","tags":["Flights"],"description":"Returns a single curated recommendation (cheapest baggage-included itinerary) for a route + date. Pricing is ranges-only — to book, hand off to the phone line via requestCallback.","parameters":[{"schema":{"type":"string","minLength":2},"example":"JFK","in":"query","name":"from1","required":true,"description":"Origin IATA airport or city code (e.g. JFK). Resolve names via searchAirports."},{"schema":{"type":"string","minLength":2},"example":"LOS","in":"query","name":"to1","required":true,"description":"Destination IATA airport or city code (e.g. LOS)."},{"schema":{"type":"string","minLength":8},"example":"2026-08-15","in":"query","name":"DepartureDate1","required":true,"description":"Outbound date in YYYY-MM-DD."},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"example":1,"in":"query","name":"Adults","required":true,"description":"Number of adult passengers (1 or more)."},{"schema":{"type":"string","minLength":2},"in":"query","name":"from2","required":false},{"schema":{"type":"string","minLength":2},"in":"query","name":"to2","required":false},{"schema":{"type":"string","minLength":8},"in":"query","name":"DepartureDate2","required":false},{"schema":{"type":"string","minLength":2},"in":"query","name":"from3","required":false},{"schema":{"type":"string","minLength":2},"in":"query","name":"to3","required":false},{"schema":{"type":"string","minLength":8},"in":"query","name":"DepartureDate3","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"Children","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"Infants","required":false},{"schema":{"type":"string","enum":["Economy","PremiumEconomy","Business","FirstClass","NoPreference"]},"example":"Economy","in":"query","name":"FlightClass","required":false,"description":"Preferred cabin class."},{"schema":{"type":"boolean"},"in":"query","name":"FlexibleDates","required":false},{"schema":{"type":"string"},"in":"query","name":"DepartureFlexInterval","required":false},{"schema":{"type":"string"},"in":"query","name":"DestinationFlexInterval","required":false},{"schema":{"type":"string"},"in":"query","name":"prefferedAirlines","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"example":{"recommendation":{"referenceNo":1042,"flight":{"AirItinerary":{"OriginDestinationOptions":[{"FlightSegments":[{"MarketingAirlineCode":"ET","FlightNumber":"508","DepartureAirportLocationCode":"JFK","ArrivalAirportLocationCode":"LOS","DepartureDateTime":"2026-08-15T21:30:00","ArrivalDateTime":"2026-08-16T11:55:00","CabinClassCode":"Y","FreeBaggages":[{"FreeQuantity":2}]}]}]}}}},"type":"object","properties":{"recommendation":{"anyOf":[{"type":"object","properties":{"referenceNo":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"flight":{}},"required":["referenceNo","flight"],"additionalProperties":false},{"type":"null"}]}},"required":["recommendation"],"additionalProperties":false}}}}},"x-openai-isConsequential":false}},"/api/flights/recommendation/{refNo}":{"get":{"operationId":"getRecommendation","summary":"Fetch a previously saved flight recommendation by reference number.","tags":["Flights"],"description":"Reads a stored recommendation snapshot by its numeric referenceNo. Helper for retrieving an earlier search result; not a primary agent tool.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"path","name":"refNo","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"referenceNo":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"origin":{"type":"string"},"destination":{"type":"string"},"departureDate":{"type":"string"},"returnDate":{"anyOf":[{"type":"string"},{"type":"null"}]},"tripType":{"type":"string"},"adults":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"children":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"infants":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cabinClass":{"anyOf":[{"type":"string"},{"type":"null"}]},"sessionId":{"type":"string"},"totalPrice":{"type":"number"},"currencyCode":{"type":"string"},"flightData":{},"searchParams":{"anyOf":[{},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","referenceNo","origin","destination","departureDate","returnDate","tripType","adults","children","infants","cabinClass","sessionId","totalPrice","currencyCode","flightData","searchParams","createdAt","updatedAt"],"additionalProperties":false}}}}},"x-openai-isConsequential":false}},"/api/flights/search/list":{"get":{"operationId":"getFareRange","summary":"Get typical fare ranges (low/high/median USD) for a route + month.","tags":["Flights"],"description":"Citation-safe fare RANGES for a route, travel month, and cabin — never a live quotable per-trip fare. Answers \"how much is X to Y\"; to book, hand off to the phone line.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":4},"example":"JFK","in":"query","name":"originCode","required":false,"description":"Origin IATA code filter."},{"schema":{"type":"string","minLength":2,"maxLength":4},"example":"LOS","in":"query","name":"destinationCode","required":false,"description":"Destination IATA code filter."},{"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"example":"2026-08","in":"query","name":"travelMonth","required":false,"description":"Travel month, YYYY-MM."},{"schema":{"type":"string","minLength":1},"example":"Economy","in":"query","name":"cabinClass","required":false,"description":"Cabin class filter (e.g. Economy)."},{"schema":{"type":"integer","minimum":1,"maximum":200},"example":50,"in":"query","name":"take","required":false,"description":"Max rows to return (1–200, default 50)."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"example":{"items":[{"id":"clz0farerange0001","originCode":"JFK","destinationCode":"LOS","travelMonth":"2026-08","cabinClass":"Economy","fareLowUsd":1061,"fareHighUsd":6179,"fareMedianUsd":1480,"sampleSize":259,"sourceUrl":null,"authorId":null,"publishedAt":"2026-06-01T00:00:00.000Z","createdAt":"2026-06-01T00:00:00.000Z","updatedAt":"2026-06-01T00:00:00.000Z"}],"count":1},"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"originCode":{"type":"string"},"destinationCode":{"type":"string"},"travelMonth":{"type":"string"},"cabinClass":{"type":"string"},"fareLowUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"fareHighUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"fareMedianUsd":{"anyOf":[{"type":"number"},{"type":"null"}]},"sampleSize":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sourceUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"authorId":{"anyOf":[{"type":"string"},{"type":"null"}]},"publishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","originCode","destinationCode","travelMonth","cabinClass","fareLowUsd","fareHighUsd","fareMedianUsd","sampleSize","sourceUrl","authorId","publishedAt","createdAt","updatedAt"],"additionalProperties":false}},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","count"],"additionalProperties":false}}}}},"x-openai-isConsequential":false}},"/api/flights/airports":{"get":{"operationId":"searchAirports","summary":"Resolve a city or airport name to IATA airport codes.","tags":["Flights"],"description":"Autocomplete helper mapping a free-text city/airport query (e.g. \"Lagos\") to IATA codes. Use to resolve origin/destination before searchFlights or getFareRange.","parameters":[{"schema":{"type":"string","minLength":1},"example":"Lagos","in":"query","name":"search","required":true,"description":"City or airport name/code to autocomplete (e.g. Lagos)."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"example":[{"Code":"LOS","Name":"Murtala Muhammed International Airport","City":"Lagos","Country":"Nigeria"}],"type":"array","items":{"type":"object","properties":{"Code":{"type":"string"},"Name":{"anyOf":[{"type":"string"},{"type":"null"}]},"Type":{"anyOf":[{"type":"string"},{"type":"null"}]},"City":{"anyOf":[{"type":"string"},{"type":"null"}]},"Region":{"anyOf":[{"type":"string"},{"type":"null"}]},"Country":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["Code","Name"],"additionalProperties":{}}}}}}},"x-openai-isConsequential":false}},"/api/flights/contact":{"post":{"operationId":"requestCallback","summary":"Request a callback from a flight specialist (creates a lead).","tags":["Flights"],"description":"Submits traveler name + phone (and optional itinerary context) so a specialist calls back to build and book the fare. Requires at least one of phone or email. Creates a lead — confirm with the user first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"example":{"name":"Ada O.","phone":"+1 555 0100","originCode":"JFK","destinationCode":"LOS","travelMonth":"2026-08","consent":true,"sourcePage":"/go/flights/jfk-los","metadata":{"aiEngine":"chatgpt"}},"type":"object","properties":{"referenceNo":{"description":"Optional reference number of a prior search recommendation to attach.","type":"integer","minimum":1,"maximum":9007199254740991},"name":{"description":"Traveler full name.","type":"string","minLength":1,"maxLength":200,"example":"Ada O."},"email":{"description":"Contact email. At least one of email or phone is required.","type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"description":"Callback phone number. At least one of email or phone is required.","type":"string","minLength":7,"maxLength":32,"example":"+1 555 0100"},"originCode":{"description":"Origin IATA code for the desired trip.","type":"string","minLength":2,"maxLength":4,"example":"JFK"},"destinationCode":{"description":"Destination IATA code for the desired trip.","type":"string","minLength":2,"maxLength":4,"example":"LOS"},"travelMonth":{"description":"Intended travel month, YYYY-MM.","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","example":"2026-08"},"sourcePage":{"description":"Path or URL the request originated from (used for attribution).","type":"string","minLength":1,"maxLength":500,"example":"/go/flights/jfk-los"},"consent":{"default":false,"description":"Traveler consent to be contacted. Must be true to request a callback.","type":"boolean"},"metadata":{"description":"Free-form context, e.g. { aiEngine: \"chatgpt\" } for attribution.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"example":{"id":"clz0contact0001","createdAt":"2026-06-09T12:00:00.000Z"},"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","createdAt"],"additionalProperties":false}}}}},"x-openai-isConsequential":true}}},"servers":[{"url":"https://api.1800airfare.com","description":"Production"},{"url":"http://localhost:3001","description":"Local development"}]}