Docs / Reference / Search API
Search API
POST /v1/search runs a flight search through TEOFetch and scores every result with TEOScore, returning fully-scored options in a single call. Use this when you want ranked results; use POST /v1/flights/search if you only need raw flight data, or POST /v1/score/score to score options you already have.
Request
POST /v1/search
Content-Type: application/json
Authorization: Bearer tfp_live_...
{
"origin": "JFK",
"destination": "LHR",
"departureDate": "2026-08-15",
"returnDate": "2026-08-22",
"passengers": { "adults": 1 },
"cabinClass": "business",
"searchMode": "all",
"searchPreferences": {
"bags": 1,
"preferredArrivalTime": "18:00"
}
}searchMode—all(cash + award),award(points/miles only), orcash(cash fares only).cabinClass—economy,premium_economy,business, orfirst. Award availability is strongest in premium cabins on long-haul routes.passengersis an object ({"adults": 1});returnDateandsearchPreferencesare optional.
Response
Returns the flight options and, alongside them, a TEOScore entry per option (keyed by option id). Provider options carry the fare details; teoscoreOptions carry the score, rank, and category breakdown.
{
"id": "q_01HXY...",
"origin": "JFK",
"destination": "LHR",
"searchMode": "all",
"providerOptions": [ { "id": "opt_01HXY...", "provider": "cash_primary", "totalPrice": 2840, "cabin": "business", "...": "..." } ],
"teoscoreOptions": [ { "optionId": "opt_01HXY...", "teoScore": 84, "rank": 1, "categoryScores": { "...": 0 } } ],
"partial": false,
"warnings": [],
"executedAt": "2026-08-01T12:00:00.000Z"
}If scoring is briefly unavailable, teoscoreOptionscomes back empty with a warnings entry and partial: true — the flight results are still returned, just unranked.
Scopes
Requires the flights.search scope — the same scope as /v1/flights/search, so any key that can search flights can call /v1/search.