travel_search_flights
Search live flight offers on travel.brij.fi (BRIJ Flight API). Free for users on BRIJ Wallet (sponsored preview, no USDC charged, up to 20 searches per account per 24h). ALWAYS call with cheapest_per_itinerary=true and a reasonable limit (10–20) unless you have a very specific reason not to: the ungrouped view is a flat price-sorted list of fare instances and a small limit on it silently discards every pricier fare variant on every flight (Comfort/Flex/refundable/business/premium-economy are ALL more expensive than Basic, so with limit=30 ungrouped you get 30 Basic/Lite offers and mistakenly conclude "no refundable exists"). The grouped view is lossless per flight: each returned offer's fare_options array carries EVERY fare variant of that physical itinerary (offer_id, brand, price, refundable, changeable, checked_bags_included), cheapest first — this is the correct source for "is there a refundable option?", "cheapest with a checked bag?", "business class?". Filters (max_stops, max_price, departure_after/before) apply BEFORE sort and limit, so "limit=5 + sort=duration + max_stops=0" means "the 5 fastest directs". Supports 1 to 9 adults and an optional cabin_class filter; pass return_date for a round trip (both directions priced together, booked in ONE /air/book, escrow amount = round-trip total; max_stops=0 then requires BOTH legs direct). Every offer carries a passenger_count (must match the passengers array sent to travel_book_flight) and a slices array (one entry per direction — the journey-level departing_at/arriving_at describe the OUTBOUND only for backward compatibility; slices is canonical for round trips). Offers that require passenger identity documents (identity_documents_required=true) are filtered out — POST /air/intents refuses them; dropped_identity_documents in the response counts how many. Truly non-stop means BOTH stops=0 AND technical_stops=0. Offers sharing the same comparison_key are the same physical itinerary (joins all directions on round trips). For extra-bag prices on a specific fare or a fresh price for a minutes-old offer, call travel_offer_details (0.01 USDC). Seat maps and full legal fare-rule text are not exposed. null/empty everywhere means the airline did not disclose the value — unknown, never zero or false. Each offer has an opaque id to pass into travel_offer_details or travel_create_booking_intent next.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Optional ordering. Ascending only. Exactly one of: price (default), duration (fastest first), departure (earliest local outbound first), emissions (lowest CO2 first, unknown values sort last). | |
| limit | No | Optional cap on the number of offers returned (offers are always sorted cheapest first before the cap). Defaults to 25; upstream can return several hundred offers so keeping a limit is important. | |
| adults | No | Number of adult passengers, 1 to 9 (airline maximum per booking). Defaults to 1 if omitted. The offer is priced for exactly this many travellers and travel_book_flight must later supply exactly this many passengers. | |
| max_price | No | Optional decimal cap on total_amount in the offer currency, e.g. "250.00". | |
| max_stops | No | Optional. Maximum plane changes PER DIRECTION. 0 = directs only (a round trip qualifies only if BOTH legs are direct). Technical stops without a plane change do not count. Omit for any. | |
| cabin_class | No | Optional cabin filter. Must be exactly one of: economy, premium_economy, business, first. Defaults to economy when omitted. | |
| depart_date | Yes | Outbound departure date in ISO 8601 format (YYYY-MM-DD), for example 2026-12-15. | |
| origin_iata | Yes | Departure airport or city. Accepts a 3-letter IATA airport code (CDG, ORY, JFK, ...) OR a 3-letter IATA metropolitan city code (PAR, LON, NYC, TYO, CHI, WAS, ROM, MIL, SAO, BUE, STO, MOW, IST, ...). Pass the city code when the user names the city; pass the airport code only when they specify an airport. | |
| return_date | No | Optional return date in ISO 8601 format (YYYY-MM-DD). When set, the search returns round-trip offers priced for BOTH directions and booked in one /air/book call — the escrow amount is the round-trip total. Omit for one-way. | |
| departure_after | No | Optional. Outbound departs at or after this time, LOCAL to the departure airport, HH:MM. Example: "12:00". | |
| departure_before | No | Optional. Outbound departs at or before this time, LOCAL to the departure airport, HH:MM. Combine with departure_after for a window (e.g. afternoon = departure_after 12:00, departure_before 18:00). | |
| destination_iata | Yes | Arrival airport or city. Accepts a 3-letter IATA airport code OR a metropolitan city code, same rule as origin_iata. | |
| cheapest_per_itinerary | No | Strongly recommended to set true. When true, the response groups by physical itinerary and each returned offer carries fare_options — the FULL list of fare variants for that flight (offer_id, brand, price, refundable, changeable, checked_bags_included). That is the correct way to answer "are there refundable / premium / with-checked-bag fares on this flight?" — do NOT set false to get variants, it does the opposite. When false (default upstream), the response is a flat list of individual fare instances sorted by price ascending; combined with a limit it returns only the N cheapest fare-instances, so the pricier variants (Comfort, Flex, refundables, business) fall off the tail. Setting it false is almost never what you want. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||