Search flight solutions (SSE stream)

post

https://example.com/v1/flights/search

Initiate a flight search and stream normalised solutions back as Server-Sent Events. Each data: event is a JSON-encoded flight solution object whose id is a canonical Mercury UUID (see POST /v1/flights/fares). The stream ends with event: done.

Send presentation: "grouped" on a two-leg (round-trip) itinerary to receive event: outbound-group frames instead — one per physical outbound, each carrying a from-price and its priced return options. See docs/adr/MER-1488-flight-grouped-search.md.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

POST body for /v1/flights/search and /v1/recommendations/flight.

Supports one-way, round-trip, and multi-city itineraries. Trip type is
auto-detected from the number of legs: one leg → one-way, two legs →
round-trip, three or more legs → multi-city.

Per-leg time ranges (departureAfter / departureBefore /
arrivalAfter / arrivalBefore) are enforced by the upstream search
provider via poll-query parameters; Mercury forwards them directly (MER-660).

The mercury/assistant/tools/search_flights/ MCP tool has its own flat
input schema and builds native provider params directly, intentionally
bypassing this type. The two schemas diverge by design — the assistant tool
is a natural-language interface while this type is the structured API
contract.

itinerary

array of objects

required

length between 1 and 10

One leg for one-way, two for round-trip, three or more for multi-city.

Itinerary*

passengers

object

Passenger type counts.

cabinClass

string

enum

Defaults to economy

economy | premium_economy | business | first

Allowed:

bookingProfile

enum

Booking profile context. personal for non-business bookings, business for business bookings.

directOnly

Restrict results to non-stop flights (MER-661). True applies the filter; False or omitted means no constraint.

priceMin

0 to 1000000000000

Minimum total price per traveler in the search currency (MER-661).

priceMax

0 to 1000000000000

Maximum total price per traveler in the search currency (MER-661).

presentation

Alternative result framing, honoured only by POST /v1/flights/search. grouped folds a round trip's solutions by their shared outbound and streams event: outbound-group frames, each carrying a from-price and its priced return options; omitted (the default) streams the flat event: solution sequence unchanged. Only applies to two-leg (round-trip) itineraries — one-way and multi-city searches stream flat regardless. POST /v1/recommendations/flight accepts the field for request-shape parity with search and ignores it: it returns ranked results rather than a stream, so there is nothing to frame. See docs/adr/MER-1488-flight-grouped-search.md.

Responses

401

Missing or invalid authentication

422

Invalid search parameters

503

Flight search provider unavailable

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here!

200SSE stream of flight search solutions