On-demand searches - Farelint

Pre-release endpoint contract. No executable API host is published yet.

Create a search

POST /v1/searches

Field	Type	Meaning
carriers	string[]	Enabled source-airline codes
origin / destination	string	IATA airport codes
departure_date	string	Local departure date, YYYY-MM-DD
return_date	string or null	Exact return date, or null for one way
passengers	object	Adults, child ages and infants
cabin	string	Requested cabin
market	string	Point-of-sale country
currency	string	Requested ISO currency; returned currency is explicit
freshness	string	`fresh_collection` requests a new source collection
max_credits	integer	Upper budget bound; reject before dispatch if the estimate exceeds it

Accepted response

{
  "example": true,
  "id": "example_search",
  "status": "queued",
  "estimated_credits": 1,
  "credits_charged": 0
}

Retrieve results

GET /v1/searches/{id} The planned job states are queued, running, completed, partial and failed. Each source carries its own status. The results distinguish a successfully observed empty search from a collection failure.

{
  "example": true,
  "id": "example_search",
  "status": "completed",
  "source_results": [{
    "carrier": "FR",
    "status": "completed",
    "observed_at": "2026-10-29T10:42:00Z",
    "source_priced_at": null,
    "observations": [{
      "price": { "amount": "89.90", "currency": "EUR", "basis": "journey_total", "taxes_included": null },
      "baggage": { "checked": null },
      "booking_verified": false
    }],
    "credits_charged": 1
  }]
}

This is a shortened schema example, not a real offer. Production observations must retain the original search identity and available itinerary/source details.

Retry safely

Reuse the same idempotency key for retries of the same body. The proposed behavior returns the original job without another charge. Changed criteria require a new key; conflicting reuse returns an error. Polling does not initiate another collection.