Get ranked, policy-compliant recommendations for a travel vertical

post

https://example.com/v1/recommendations/{vertical}

Search and rank travel options for the given vertical, applying the account's corporate policy to each result.

Returns a curated ranked list of options with compliance status, policy violations, comparison labels, and a per-dimension feature breakdown. The pipeline runs the full multi-signal scoring path (context + filter + score + rank).

The context-data quality is surfaced in the X-Recommendation-Context-Quality response header with values FULL, PARTIAL, LOCAL_ONLY, or NONE.

Supported verticals: flight, stay, train, and car.

The trip multi-vertical bundler is available as a separate endpoint (/v1/recommendations/trip) planned in a follow-up ticket.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

vertical

string

enum

required

Allowed:

Query Params

compliance_weight

number

0 to 1

Defaults to 0

Compliance weight in [0.0, 1.0]. Default 0.0 — HardFilter removes non-compliant options, so compliance has no ranking signal in normal traffic. 0.25 restores the pre-MER-994 balanced profile; 1.0 gives pure-compliance ranking (MER-18). A/B testing only.

include_fare

boolean

Defaults to true

When true (default), enrich each top-N ranked option with a selected fare via the post-rank FareStage. False skips fare fan-out (useful when only ranking metadata is needed).

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

400

Request body is not valid JSON

401

Missing or invalid authentication

403

Account identity missing from token

422

Invalid search parameters or unknown vertical

503

Search provider or policy service unavailable

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Curated ranked list of travel options