{"uid":"cap_SBiiGf-7eh4GKgokHbbQW","slug":"brij-flight-search-0e921506","name":"BRIJ Flight Search","description":"Flight search can be paid with x402 or sponsored by the BRIJ gateway.\n\nFor direct x402 clients, send a valid `PAYMENT-SIGNATURE` header. Without\npayment, the API returns `402 Payment Required` carrying the **current** price.\n\nFor BRIJ Wallet preview calls, the gateway may send `X-BRIJ-SPONSORED-*`\nheaders. Providers should treat that as a BRIJ-sponsored preview, not as a\nuser-paid x402 settlement.\n\nEvery price in the response is the price a buyer pays: total_amount / total_amount_decimal (offers, fare_options, highlights) are all-in, and max_price filters on that figure. POST /air/intents asks exactly this amount as expected_escrow_amount (a wallet enrolled in a fee-waiving cohort is asked less, never more).\n\nBase x402 price is 0.10 USDC. The price is multiplied (up to 50×) by the\ncurrent search load: completed searches in the last 60 seconds and\nany upstream rate-limit response in the last 5 minutes. Always read\nthe latest `PAYMENT-REQUIRED` challenge before signing - the price\nyour client saw a moment ago may already be stale.\n\n\nThe same flight commonly appears several times at different prices: each offer is one fare (fare_brand_name, baggage, change/refund conditions) sold by one seller (owner_name). Two offers on the same flight can share identical conditions and differ only in seller and price — compare the fare fields, never assume cheaper means more restrictive.\n\n**Data boundaries — what this response does and does not contain.**\nEach offer carries EVERYTHING the flight inventory provider discloses at search time: itinerary (legs, times with IANA timezones, durations, aircraft, terminals, technical stops), identity (comparison_key, both carriers on codeshares, flight numbers, fare_basis_code), fare content (brand, cabin, included baggage, change/refund conditions with penalties), price breakdown (base + tax), CO2 estimate, and loyalty programmes. To drill into ONE offer — fresh price/expiry and paid-ancillary prices — use POST /air/offer-details. Filters (max_stops, departure_after/before, max_price) apply before sort, grouping and limit — so limit + sort=duration + max_stops=0 means \"the fastest directs\". Offers default to cheapest first; a full response can exceed 300 KB, so LLM-driven agents should send cheapest_per_itinerary=true with a limit and drill into finalists.\n\nNot available in SEARCH results (use POST /air/offer-details per offer):\n- Prices of paid ancillaries (extra checked bags and other extras).\n- Seat maps and specific seat availability.\n- Full legal fare-rule text. It does not exist upstream in machine form: the structured conditions object IS the complete machine-readable ruleset. For airline-side research, fare_basis_code plus the marketing carrier identifies the exact fare.\n\nEverywhere in this response, null/empty means the airline did not disclose the value — unknown, never zero or false.\n\n**Anti-pattern — truncation without grouping.** cheapest_per_itinerary=false combined with a small limit returns the N cheapest fare INSTANCES, not the N cheapest itineraries. Basic/Lite fares are always cheaper than Comfort/Flex/refundable/business variants of the SAME flight, so the pricier variants sort to the tail and fall off — and their absence from a truncated response proves nothing. To answer \"is there a refundable / with-bag / higher-cabin fare?\", always use cheapest_per_itinerary=true and read fare_options; it is lossless on price, brand, refund/change conditions and checked bags.\n\n**Progressive results.** The response may carry `status: enriching` plus a `search_id`: slower, cheaper fulfiller tiers are still quoting. Poll the free POST /air/search-updates with that `search_id` (every ~`poll_after_ms`) to receive their offers as they land, until `status: complete`. If you skip polling you simply act on the fast tiers' offers — nothing else changes.","url":"https://travel.brij.fi/air/search?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","required":["origin_iata","destination_iata","depart_date"],"properties":{"sort":{"enum":["price","duration","departure","emissions","nonstop_first"],"type":"string","description":"Ordering, ascending only. Default price. duration = fastest first, departure = earliest local departure first, emissions = lowest CO2 first (unknown values sort last). nonstop_first = every nonstop itinerary (price-ascending) before any connection — with a limit, directs survive the cut."},"limit":{"type":"integer","minimum":1,"description":"Optional. Cap the number of offers returned; 0 or absent returns every match. Offers are sorted per `sort` (cheapest first by default), so a limit keeps the best ones under that order. ONE EXCEPTION, and it is why the array can hold limit+1 rows: when the cut would have dropped the cheapest NONSTOP, that offer is appended as the last row, so a page never hides that a direct exists even from a caller that reads no other field. It is appended, never inserted at its price rank — the first `limit` rows are still the `limit` best under your sort, and offers[0] is still the cheapest. `highlights` names it too."},"adults":{"type":"integer","maximum":9,"minimum":1,"description":"Adult passengers, 1 to 9 (the airline maximum per booking). The offer is priced for this many travellers, and /air/book must later supply exactly this many passengers."},"max_price":{"type":"string","example":"250.00","description":"Decimal cap on total_amount in the offer currency, e.g. \"250.00\"."},"max_stops":{"type":"integer","minimum":0,"nullable":true,"description":"Maximum plane changes PER DIRECTION: 0 keeps directs only (a round trip qualifies only if both legs are direct). Absent = any. Technical stops without a plane change do not count."},"cabin_class":{"enum":["economy","premium_economy","business","first"],"type":"string","description":"Optional, defaults to economy."},"depart_date":{"type":"string","format":"date","example":"2026-06-10"},"origin_iata":{"type":"string","example":"MAD","maxLength":3,"minLength":3},"return_date":{"type":"string","format":"date","example":"2026-08-22","description":"Optional. Adds the inbound slice (destination back to origin on this date). Round-trip offers cover both directions and are booked in ONE /air/book — the escrow amount is the round-trip total."},"departure_after":{"type":"string","example":"12:00","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","description":"Outbound departs at or after this time, LOCAL to the departure airport, HH:MM."},"departure_before":{"type":"string","example":"18:00","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","description":"Outbound departs at or before this time, local HH:MM. Combine with departure_after for a window: afternoon = after 12:00, before 18:00."},"destination_iata":{"type":"string","example":"LIS","maxLength":3,"minLength":3},"cheapest_per_itinerary":{"type":"boolean","description":"Optional. Return only the cheapest fare of each physical itinerary (comparison_key); the folded fares stay visible in each offer's fare_options (offer_id, brand, price, refundable, changeable, checked bags), so refundability questions are answerable from the grouped data itself. Recommended for LLM-driven agents together with limit."}}},"responseSchema":{"type":"object","required":["search"],"properties":{"search":{"type":"object","required":["request_id","offers"],"properties":{"offers":{"type":"array","items":{"type":"object","required":["id","owner_name","origin_iata","destination_iata","departing_at","arriving_at","origin_time_zone","destination_time_zone","stops","technical_stops","duration","comparison_key","fare_brand_name","cabin_class","checked_bags_included","carry_on_bags_included","conditions","slices","total_emissions_kg","identity_documents_required","total_amount","total_amount_decimal","total_currency","requires_instant_payment"],"properties":{"id":{"type":"string","example":"fastbooking:off_0000B5xGbDG4ifAoeDTtG9"},"stops":{"type":"integer","example":1,"description":"Number of connections. 0 means a direct flight."},"slices":{"type":"array","items":{"$ref":"#/components/schemas/OfferSlice"},"description":"Each direction of the journey: one entry for a one-way, two for a round trip (outbound then inbound). The journey-level fields above describe the OUTBOUND for compatibility; slices is the canonical and only complete view for round trips. comparison_key joins all directions, so two round trips sharing an outbound but not a return stay distinct."},"duration":{"type":"string","example":"PT7H28M","description":"Whole-journey duration, ISO 8601."},"segments":{"type":"array","items":{"$ref":"#/components/schemas/OfferSegment"},"description":"Every leg of the itinerary, in order."},"conditions":{"allOf":[{"$ref":"#/components/schemas/FareConditions"}],"nullable":true,"description":"Change/refund permissions for this fare; null when the airline disclosed nothing."},"expires_at":{"type":"string","format":"date-time"},"owner_name":{"type":"string","example":"Air Europa"},"arriving_at":{"type":"string","example":"2026-08-02T21:10:00","description":"FINAL arrival at the journey destination, airport-local time with no UTC offset."},"cabin_class":{"type":"string","example":"economy","description":"Normalized cabin: economy, premium_economy, business, first. Empty when unknown."},"origin_iata":{"type":"string","example":"MAD","description":"Start of the whole journey (first leg's origin)."},"departing_at":{"type":"string","example":"2026-08-02T14:42:00","description":"Journey departure, airport-local time with no UTC offset."},"fare_options":{"type":"array","items":{"$ref":"#/components/schemas/OfferFareOption"},"description":"Present on cheapest_per_itinerary searches: EVERY fare of this itinerary (this offer included), cheapest first. The grouped view is lossless on price, brand, refund/change conditions and checked bags — never claim such a fare does not exist without reading this list."},"tax_currency":{"type":"string","example":"USD"},"total_amount":{"type":"integer","format":"int64","example":67600000,"description":"Atomic amount used by the API for money comparisons."},"base_currency":{"type":"string","example":"USD"},"passenger_ids":{"type":"array","items":{"type":"string"}},"comparison_key":{"type":"string","example":"cmp_abc123","description":"Identifies the physical itinerary: offers with the SAME comparison_key are the same flights at different fares or sellers. Group by it to deduplicate results (a search commonly returns 100+ offers for a few dozen itineraries)."},"total_currency":{"type":"string","example":"USD"},"fare_brand_name":{"type":"string","example":"Flexible Balearic","description":"Airline's name for this fare (e.g. \"Basic\", \"Flexible Balearic\"). The SAME flight is listed once per fare and per seller: use this plus conditions, baggage and owner_name to tell same-flight offers apart. Empty when the airline did not name the fare."},"technical_stops":{"type":"integer","description":"Refuelling-type stops across all legs, without plane change. Truly non-stop = stops 0 and technical_stops 0."},"destination_iata":{"type":"string","example":"LIS","description":"End of the whole journey (last leg's destination), NOT the first connection point."},"origin_time_zone":{"type":"string","example":"America/New_York","description":"IANA timezone of the journey origin."},"fare_options_count":{"type":"integer","description":"Present only on cheapest_per_itinerary searches: how many fares of this same itinerary were collapsed into this cheapest one."},"tax_amount_decimal":{"type":"string","example":"24.50"},"total_emissions_kg":{"type":"string","example":"21","description":"Estimated CO2 for the journey, decimal kilograms. Empty when the provider does not report it. Varies several-fold between offers on the same route."},"base_amount_decimal":{"type":"string","example":"65.00","description":"Fare before tax; total = base + tax."},"payment_required_by":{"type":"string","format":"date-time"},"total_amount_decimal":{"type":"string","example":"67.60"},"checked_bags_included":{"type":"integer","nullable":true,"description":"Checked bags included for the WHOLE journey (minimum across legs). null = the airline did not say — do not assume 0."},"destination_time_zone":{"type":"string","example":"America/Los_Angeles","description":"IANA timezone of the journey destination."},"carry_on_bags_included":{"type":"integer","nullable":true,"description":"Carry-on bags included for the whole journey. null = unknown."},"requires_instant_payment":{"type":"boolean"},"cabin_class_marketing_name":{"type":"string","example":"ECONOMY","description":"The airline's own name for the cabin."},"price_guarantee_expires_at":{"type":"string","format":"date-time"},"identity_documents_required":{"type":"boolean","description":"true = this fare demands passenger identity documents, which this API cannot collect: POST /air/intents refuses such offers with 409 identity_documents_not_supported. Filter them out before choosing."},"supported_loyalty_programmes":{"type":"array","items":{"type":"string"},"description":"IATA codes of airline loyalty programmes this offer can credit miles to (e.g. BA, AF, UA). Empty when none or unknown."}}}},"status":{"enum":["complete","enriching"],"type":"string","description":"\"complete\" when every fulfiller tier has finished quoting; \"enriching\" while slower tiers are still adding offers — poll /air/search-updates to receive them."},"search_id":{"type":"string","example":"srch_2f7c1de09ab34455ee01aa8b90c2d711","description":"Capability token for POST /air/search-updates. The search answers fast with the quick fulfillers' offers; slower tiers keep adding offers for a couple of minutes, and this token reads them as they land. Unguessable; expires ~5 minutes after the search. Treat it like a secret."},"fulfillers":{"type":"object","description":"Per-tier quoting state, e.g. {\"fastbooking\": \"complete\", \"trip.com\": \"running\"}.","additionalProperties":{"enum":["complete","running"],"type":"string"}},"highlights":{"type":"object","properties":{"fastest":{"type":"object","required":["offer_id","total_amount_decimal","total_currency","duration","stops","departing_at"],"properties":{"stops":{"type":"integer","description":"Total plane changes across every direction; 0 = nonstop both ways."},"duration":{"type":"string","example":"PT23H30M","description":"Whole journey, every direction summed, ISO 8601."},"offer_id":{"type":"string","example":"fastbooking:off_0000B9nB2EOrQ54IWMWb3F","description":"Bookable like any other offer (POST /air/offer-details, then /air/intents), whether or not it appears in offers."},"carrier_name":{"type":"string","example":"British Airways"},"departing_at":{"type":"string","example":"2026-11-12T18:00:00","description":"Local departure of the first segment."},"total_currency":{"type":"string","example":"USD"},"total_amount_decimal":{"type":"string","example":"1300.97","description":"The price a buyer pays for this offer — what POST /air/intents asks as expected_escrow_amount."}}},"cheapest":{"type":"object","required":["offer_id","total_amount_decimal","total_currency","duration","stops","departing_at"],"properties":{"stops":{"type":"integer","description":"Total plane changes across every direction; 0 = nonstop both ways."},"duration":{"type":"string","example":"PT23H30M","description":"Whole journey, every direction summed, ISO 8601."},"offer_id":{"type":"string","example":"fastbooking:off_0000B9nB2EOrQ54IWMWb3F","description":"Bookable like any other offer (POST /air/offer-details, then /air/intents), whether or not it appears in offers."},"carrier_name":{"type":"string","example":"British Airways"},"departing_at":{"type":"string","example":"2026-11-12T18:00:00","description":"Local departure of the first segment."},"total_currency":{"type":"string","example":"USD"},"total_amount_decimal":{"type":"string","example":"1300.97","description":"The price a buyer pays for this offer — what POST /air/intents asks as expected_escrow_amount."}}},"cheapest_nonstop":{"type":"object","required":["offer_id","total_amount_decimal","total_currency","duration","stops","departing_at"],"properties":{"stops":{"type":"integer","description":"Total plane changes across every direction; 0 = nonstop both ways."},"duration":{"type":"string","example":"PT23H30M","description":"Whole journey, every direction summed, ISO 8601."},"offer_id":{"type":"string","example":"fastbooking:off_0000B9nB2EOrQ54IWMWb3F","description":"Bookable like any other offer (POST /air/offer-details, then /air/intents), whether or not it appears in offers."},"carrier_name":{"type":"string","example":"British Airways"},"departing_at":{"type":"string","example":"2026-11-12T18:00:00","description":"Local departure of the first segment."},"total_currency":{"type":"string","example":"USD"},"total_amount_decimal":{"type":"string","example":"1300.97","description":"The price a buyer pays for this offer — what POST /air/intents asks as expected_escrow_amount."}}}},"description":"The three offers an agent asks about first — cheapest, fastest, cheapest nonstop — each taken from EVERYTHING that matched, before the limit cut. A page of the 15 cheapest is only honest if it says what it left out: on a long-haul route every one of the 15 cheapest can be a connection while a direct exists at a higher price. Read cheapest_nonstop before concluding a route has no direct flight. A field is absent when no offer qualifies (no nonstop on the route, or none within max_stops / the time window)."},"request_id":{"type":"string","example":"orq_0000B5xGbA4yXTVomvGU2G"},"matched_count":{"type":"integer","description":"How many offers survived the filters and grouping BEFORE the limit cut — what a full listing would hold."},"poll_after_ms":{"type":"integer","description":"Suggested delay before the next /air/search-updates poll. Absent when the search is complete."}}}}},"example":null,"exampleRequest":null,"tags":["x402","shopping"],"displayCostAmount":"0.1","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.1/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.1","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.1","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_HitQyFIdOziIH_2LyRKWD","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.1","costPer":"request","priority":0,"asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Search for available one-way flights between two airports on a given date, returning a list of fare offers with pricing and timing details.","exampleAgentPrompt":"Find me available flights from Madrid (MAD) to Lisbon (LIS) on June 10, 2026 for 2 adults — show me the options with prices and departure times.","exampleUseCases":[{"title":"Compare weekend flight options and pricing","prompt":"What one-way flights can I book from New York (JFK) to Los Angeles (LAX) this Saturday? Show me what's available with departure times and total fares."},{"title":"Search international airfare on a budget","prompt":"I need to fly from Paris (CDG) to London (LHR) on July 15th for just myself. Can you find me the cheapest one-way options available that day?"},{"title":"Plan group travel with multiple passengers","prompt":"We're looking for flights from Chicago (ORD) to Miami (MIA) on August 3rd for 4 passengers. What airlines and prices do you have available?"}],"resultDescription":"Returns a search object containing a request_id and an array of flight offers. Each offer includes the offer ID, airline name (owner_name), origin and destination IATA codes, departure and arrival datetimes, total fare in both atomic integer and decimal string formats, currency code, offer expiry, price guarantee expiry, payment deadline, passenger IDs, and a flag indicating whether instant payment is required.","failureModes":["402 Payment Required — no valid PAYMENT-SIGNATURE header provided; response includes current price challenge (may be higher than cached price due to load multiplier up to 50×)","400 Bad Request — missing required fields (origin_iata, destination_iata, or depart_date), or IATA codes not exactly 3 characters","No offers returned — no flights available for the requested route/date combination","Stale price signature — price has changed due to load since client last fetched 402 challenge; must re-fetch current price before signing","Upstream rate limit — search load surcharge applies for next 5 minutes after upstream provider rate-limits"],"whenToPreferThis":"Use this endpoint when you need to search one-way flight availability and pricing between two IATA-coded airports on a specific date, and your client supports x402 micropayment headers or BRIJ-sponsored preview calls. Prefer this over generic travel APIs when you need real-time fare offers with price guarantees and atomic pricing data suitable for programmatic booking flows.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-27T06:34:18.048Z","isFirstParty":false,"canonicalSlug":"brij-flight-search-0e921506"}