Search, compare, and score flights with jetlag optimization. Includes booking via Kiwi/Duffel APIs
POST /api/v1/flights/search — live Kiwi search + DB fallback
Body: { from: "JFK", to: "LHR", date: "2026-03-15", returnDate?: "2026-03-22", cabinClass?: "economy" }
Free tier: 5 results. Concierge: 50 results. Sorted by jetlag composite DESC, then price ASC.
POST /api/flights/search/agent — multi-provider parallel search (Kiwi + Duffel) Same body. Returns UnifiedFlight[] with provider, price, jetlagScore, segments. 15-second per-provider timeout. Dedup by flight number + departure time (5min tolerance, 5% price).
POST /api/flights/validate — pre-booking price check
Body: { flightId, provider, offerId }
Returns: { valid, currentPrice, priceChanged }
POST /api/flights/book — book via AgentBookingService
Body: { flightId, provider, offerId, passengers: [...], payment: { stripePaymentMethodId } }
NEVER submit payment without explicit user approval.
Only when API returns deepLink or provider unavailable:
POST /api/v1/flights/compare — compare 2-10 flights with recommendation + deltas POST /api/v1/flights/score — jetlag K2 score (0-100), direction, recoveryDays, strategies GET /api/v1/flights/lookup/{carrier}/{number} — live Amadeus + mv_flight_schedules fallback GET /api/flights/providers/status — circuit breaker state for Kiwi and Duffel (check before booking)
Use the Scrapling /search endpoint for aggregator searches. Returns pre-parsed structured JSON —
no browser snapshot/type/click needed. Helsinki server shows EUR prices.
Reference: Scrapling Documentation
POST {SCRAPLING_URL}/search
{"site":"google-flights","origin":"LAX","destination":"NRT","departure":"2026-03-15","return":"2026-03-22"}
Returns: {"results": [{"airline":"..","price":"€1,216","duration":"11 hr 50 min","stops":"Nonstop"}], "count": N}
POST {SCRAPLING_URL}/search
{"site":"kayak","origin":"LAX","destination":"NRT","departure":"2026-03-15","return":"2026-03-22"}
/search in parallel for comparison dataIf Scrapling returns challenge != "pass" or 0 results:
ZIP package — ready to use