# Fly Frugal public travel API

Base URL: `https://flyfrugal.fyi`

This API exposes public, read-only itinerary previews, current observed flight fares, today's verified deals, route history, supported airports, and typical destination weather. No private or administrative operations are part of this contract.

No authentication is required. All responses are JSON unless stated otherwise.

## Itineraries

### List published previews

```http
GET /api/itineraries?limit=24&country=Thailand
```

- `limit`: optional integer from 1–50; defaults to 24.
- `country`: optional case-insensitive country filter.
- Full paid itinerary content and private PDF locations are never returned.

### Get one published preview

```http
GET /api/itineraries/thailand
```

The path uses the itinerary's lowercase, hyphenated slug.

## Flights and deals

### List current observed deals

```http
GET /api/deals?origin=SFO&nights=7&limit=20
```

- `origin`: optional supported three-letter IATA departure airport. Defaults to SFO unless `scope=global` is used.
- `scope=global`: searches across supported departure airports.
- `nights`: optional integer from 1–30; defaults to 7.
- `limit`: optional integer from 1–100; defaults to 100.
- Results are ordered with fresh verified savings first, followed by other current observations.

Fares are observed snapshots and can change or sell out. A savings value is shown only when Fly Frugal has a Google price insight for that specific fare.

### Today's verified deals

```http
GET /api/deals?scope=global&nights=7&fresh=today&limit=2
```

`fresh=today` returns only fares whose Google savings insight was checked today in the `America/Los_Angeles` product timezone. When none qualify, `deals` is an empty array; old data is not substituted.

### Compare dates for one route

```http
GET /api/calendar?origin=SFO&destination=NRT&nights=7
```

Returns current future travel dates and observed price context for one supported route. The result includes a summary plus up to 400 dated observations.

### Price history for one exact trip

```http
GET /api/history?origin=SFO&destination=NRT&departure=2027-04-01&return=2027-04-08&nights=7
```

Returns up to 100 stored price observations for the exact route, dates, and trip length.

### Supported airports

```http
GET /api/catalog
```

Returns supported departure airports and destination metadata.

### Typical weather

```http
GET /api/weather?airport=NRT&date=2027-04-01
```

Returns historical seasonal context, not a future forecast. The response identifies the typical month, temperature ranges, and historical rain frequency.

## Errors

Invalid public requests return an HTTP `400` response with an `error` string. Missing published resources return `404`. Temporary upstream failures may return `502` or `503`.

## MCP

Agents can use the read-only MCP endpoint at `https://flyfrugal.fyi/mcp`. See [`itinerary-mcp.md`](./itinerary-mcp.md) for client configuration and tool definitions.

## Machine-readable contract

See [`public-api.openapi.yaml`](./public-api.openapi.yaml).