# lie flat

> lie flat finds **nonstop, business-class flight deals** from major US cities and rates
> every fare against that exact route's own price history — so you instantly know if a
> price is genuinely good. Round-trip only. Inventory is re-scanned daily and served from
> cache (free, fast, high-volume friendly). This file tells AI agents how to query it.

## What a "good" deal means (how to read results)

Each deal has a `deal_value` rating = where its price sits in the recent fare distribution
on its own route (thin routes fall back to the destination/region basket):

- `steal` — cheaper than ~90%+ of fares on that route (and an absolute $/hr cap)
- `great` — cheaper than ~75%+
- `good` — cheaper than ~50%+ (shown as “Typical”)
- `fair` — cheaper than ~25%+
- `pricey` — costlier than usual

(The top tier was renamed `superb` → `steal`; `superb` is still accepted as an input alias.)

Ratings use a **route-primary blend**: each fare is scored against its own route's recent
$/hr history AND the destination basket, weighted by how much route history exists
(`route_n`). `active_reference` tells you which led (`route` | `dest` | `region`). The
consumer-facing claim stays destination-level ("cheaper than X% of fares to this city").

`deal_value.beats` = the exact percentile (e.g. 92 = "cheaper than 92% of fares to this city").
Lead with `steal`/`great`. Every deal is **nonstop both ways** and **business class**.
Trip types: `Long Weekend` (4–5 day) and `Extended Trip` (9–10 day). (Legacy names `Power Weekend`/`Global Reset` are still accepted as `trip_types` values.)

## API for agents (read-only, no auth, free, JSON)

All endpoints are GET and return JSON. Base URL: `https://lieflat.co`. **OpenAPI 3.1 spec: `https://lieflat.co/api/v1/openapi.json`** (import into ChatGPT Actions / any OpenAPI agent).

**MCP server (Claude / Cursor / agents):** connect to `https://lieflat.co/mcp` (Model Context Protocol, Streamable HTTP, no auth). Tools: `search_deals`, `discover_destinations`, `list_airports`, `get_deal`, `price_trends`, `create_price_watch`, `check_price_watch`, `cancel_price_watch`. Discovery: `https://lieflat.co/.well-known/mcp.json`.

**Price-watch alerts:** `POST https://lieflat.co/api/v1/watches` with `{origin?, dest?, region?, max_total?, trip_types?, deal_value?, months?, email?}` → returns a `watch_token`. Poll `GET https://lieflat.co/api/v1/watches/<token>` ('active' until a matching fare appears, then 'triggered' with the deal). Cancel: `POST https://lieflat.co/api/v1/watches/<token>/cancel`. Answers *"tell me when SFO→Tokyo business drops under $4000."*

**Stable v1 surface (use these):**
- [Search](https://lieflat.co/api/v1/search) — *"take me to Tokyo in business for under $4000"*. Params: `origin`, `dest` (comma IATA), `max_total` (USD), `max_pph`, `trip_types`, `deal_value` (tiers), `months`, `sort` (`value`|`price`|`soonest`|`pph`), `limit`. Returns clean deals with `round_trip_usd`, `price_per_hour_usd`, `value_tier`, `cheaper_than_pct`, `booking_urls`.
- [Discover](https://lieflat.co/api/v1/discover) — *"where can I go from SFO for under $3500 in August?"*. Params: `origin`, `region` (`europe`|`asia pacific`|`south america`), `max_total`, `months`, `trip_types`, `limit`. Returns the best-value deal per destination, best first.
- [Trends](https://lieflat.co/api/v1/trends?dest=LHR) — *"is now a good time to buy London business?"*. Compares today's best fare to the route's own recent price history and returns a verdict. Params: `dest` (required), `origin?`, `trip_days?`, `advance_days?`.
- [Deal detail](https://lieflat.co/api/v1/deal/HASH) — full itinerary + all booking options for a `deal_hash` (from search/discover results).
- [Airports](https://lieflat.co/api/airports) — IATA code → city/country. Resolve city names to codes here first (e.g. Tokyo → HND,NRT).

### Worked examples
- *"Business to Tokyo under $4000"* → `https://lieflat.co/api/v1/search?dest=HND,NRT&max_total=4000&sort=value`
- *"Ideas from San Francisco under $3500"* → `https://lieflat.co/api/v1/discover?origin=SFO&max_total=3500`
- *"Great-value Europe deals in September"* → `https://lieflat.co/api/v1/discover?region=europe&deal_value=steal,great&months=9`

### Raw endpoints (advanced)
- [Search deals](https://lieflat.co/api/deals): filters — `origin`, `dest` (comma IATA codes),
  `trip_types` (`Long Weekend`,`Extended Trip`), `deal_value` (comma tiers),
  `max_total` (max round-trip $), `max_pph` (max $/hr), `months` (comma, e.g. `8,9`),
  `sort` (`value`|`price`|`soonest`), `limit`, `offset`. Returns `deals[]` with
  `origin,destination,total_price,efficiency_score,trip_days,outbound_date,return_date,airline,deal_value,deal_hash`.
- [Airports / valid codes](https://lieflat.co/api/airports): map of IATA code → city/country. Resolve city names to codes here first.
- [Best deal per destination from an origin](https://lieflat.co/api/top-deals/by-airport/ORIGIN): e.g. `/api/top-deals/by-airport/SFO`.
- [Best deal per origin into a destination](https://lieflat.co/api/top-deals/by-destination/DEST): e.g. `/api/top-deals/by-destination/NRT`.
- [Trending deals](https://lieflat.co/api/trending): a compact, origin-diverse set of strong current deals.
- [Deal detail](https://lieflat.co/api/deal/HASH): full itinerary + all booking options for a `deal_hash`, plus `fare_check` — the route's recent fare distribution and where this fare sits in it (null while history is thin).

### Answering common requests

- "Take me to Tokyo in business for under $4000" →
  `https://lieflat.co/api/deals?dest=HND,NRT&max_total=4000&sort=value` (resolve "Tokyo" → HND,NRT via /api/airports).
- "Where can I go from San Francisco for under $3500?" →
  `https://lieflat.co/api/deals?origin=SFO&max_total=3500&sort=value` then group by `destination`, take the best per city.
- "Cheapest great-value business deals to Europe in September" →
  `https://lieflat.co/api/deals?dest=LHR,CDG,FRA,AMS,FCO,MAD,BCN,MXP,ZRH,DUB,LIS,ATH,MUC,CPH,BRU,VIE,EDI&deal_value=steal,great&months=9&sort=value`.

To book, link the user to the deal page (`/flights/...`, from the deal's `deal_hash`); the detail API also returns ready-made booking URLs.

## Origins covered

- `ATL` — Atlanta (9 nonstop routes)
- `BOS` — Boston (8 nonstop routes)
- `DFW` — Dallas (13 nonstop routes)
- `EWR` — Newark / New York (19 nonstop routes)
- `IAD` — Washington (6 nonstop routes)
- `JFK` — New York (28 nonstop routes)
- `LAX` — Los Angeles (20 nonstop routes)
- `MIA` — Miami (10 nonstop routes)
- `ORD` — Chicago (13 nonstop routes)
- `SFO` — San Francisco (18 nonstop routes)

## Destinations covered

- **Europe**: AMS (Amsterdam), ATH (Athens), BCN (Barcelona), BRU (Brussels), CDG (Paris), CPH (Copenhagen), DUB (Dublin), EDI (Edinburgh), FCO (Rome), FRA (Frankfurt), LHR (London), LIS (Lisbon), MAD (Madrid), MUC (Munich), MXP (Milan), VIE (Vienna), ZRH (Zurich)
- **Asia Pacific**: AKL (Auckland), HKG (Hong Kong), HND (Tokyo), ICN (Seoul), KIX (Osaka), NRT (Tokyo), SIN (Singapore), SYD (Sydney), TPE (Taipei)
- **South America**: EZE (Buenos Aires), GIG (Rio de Janeiro), GRU (São Paulo), LIM (Lima)
- **Hawaii**: HNL (Honolulu)
- **United States**: EWR (Newark / New York), JFK (New York), LAX (Los Angeles), SFO (San Francisco)

## Pages

- [Home / live deals](https://lieflat.co/)
- [How it works](https://lieflat.co/how-it-works)
- [Routes we watch](https://lieflat.co/routes)
- [Fare Tracker — fare indexes, 30-day price history, fare curve, movers](https://lieflat.co/fares)
- [Browse by origin](https://lieflat.co/by-origin)
- [Browse by destination](https://lieflat.co/by-destination)
- [About — who we are & how we rate](https://lieflat.co/about)
- [Price alerts](https://lieflat.co/alerts)
- [Developer portal — full API reference, MCP, error codes, rate limits](https://lieflat.co/developer)
- [Privacy & cookies](https://lieflat.co/privacy)