# Flight search API

Reference for Munition's flight routes: live flight offers, airport search and offer details. Routes, input schema, output, price and limits.

Live flight offers come from Duffel. Munition sells three paid lookups, a flight search, an airport search and the details of one offer, plus free links that start the same search on KAYAK or Kiwi.com. None of them books a flight: Munition does not reserve seats or charge airfare.

## Routes and prices

### Search flights

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/flights/search` | `search_flights_direct` | 0.05 |
| MPP | `POST /v1/mpp/flights/search` | `search_flights_mpp` | 0.05 |
| Account balance | MCP tool `search_flights` | `search_flights` | 0.05 |

### Search airports

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `POST /v1/airports/search` | `airports_search_direct` | 0.001 |
| Account balance | MCP tool `airports_search` (remote connector only) | `airports_search` | 0.001 |

### Offer details

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| x402 | `GET /v1/flights/offers/{id}` | `flight_offer_details_direct` | 0.01 |
| Account balance | MCP tool `flight_offer_details` | `flight_offer_details` | 0.01 |

### Booking links

| Paid with | Route or tool | Tool id | Price (USDC) |
| --- | --- | --- | --- |
| Free | `POST /v1/tools/flight-booking-links` | — | Free |
| Free | MCP tool `flight_booking_links` | — | Free |

Airport search and offer details have no MPP route.

## Search flights

On the x402 route the payment is verified before the body is checked; on the MPP route the body is checked first. Either way, an invalid body, such as a departure date in the past, gets `400` before settlement and costs nothing.

Body of `POST /v1/flights/search`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `origin` | string | yes | — | The 3-letter IATA code of the departure airport, such as `SFO`. Upper or lower case. |
| `destination` | string | yes | — | The 3-letter IATA code of the arrival airport, such as `NRT`. |
| `departureDate` | string | yes | — | `YYYY-MM-DD`, a real calendar date, not in the past. |
| `returnDate` | string | no | — | `YYYY-MM-DD`, on or after `departureDate`. Leave it out for a one-way search. |
| `adults` | integer | no | 1 | 1 to 9. |
| `children` | integer | no | 0 | 0 to 9. |
| `infants` | integer | no | 0 | 0 to 9. |
| `travelClass` | string | no | ECONOMY | `ECONOMY`, `PREMIUM_ECONOMY`, `BUSINESS` or `FIRST`. |
| `nonStop` | boolean | no | — | `true` keeps only offers whose itineraries each have one segment. |
| `maxResults` | integer | no | 50 | 1 to 50. |
| `maxPrice` | number | no | — | Drops offers whose total price is above it. Prices are not converted between currencies. |
| `currency` | string | no | — | A 3-letter currency code for `maxPrice`: offers in other currencies are then kept as they are. |

Response of `POST /v1/flights/search`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `results` | array of objects | yes | The offers. Each has `id` (use it for offer details), `source`, `totalPrice` (a string), `currency`, `airlineCodes` and `itineraries`; each itinerary has `duration`, `numberOfStops` and `segments`, each segment `departure` and `arrival` (`airportCode`, `at`), `carrierCode`, `operatingCarrierCode`, `flightNumber`, `aircraft` and `duration`. |
| `meta` | object | yes | `resultCount` and `searchedAt`. |
| `warnings` | array of strings | no | Notes on filters applied, such as non-stop or price filtering. |

The response also has a `run` object, which the published schema does not list: the paid call's `id`, with `receiptUrl`, `feedbackUrl` and `pageUrl` links.

## Search airports

Resolve a city, an airport name or a country to airport codes before a flight search.

Body of `POST /v1/airports/search`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `query` | string | yes | — | An IATA code, a city, an airport name or a country, 1 to 100 characters. |

Response of `POST /v1/airports/search`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `query` | string | yes | The query you sent. |
| `airports` | array of objects | yes | Each has `iataCode`, `name`, `cityName`, `countryCode` and `countryName`, and when known `timeZone` and `coordinates` (`lat`, `lng`). |
| `meta` | object | yes | `resultCount` and `searchedAt`. |

## Offer details

`GET /v1/flights/offers/{id}` has no body: `{id}` is the `id` of an offer from a flight search, up to 256 characters. It returns the offer's baggage, cabin, fare conditions, segments and total price, and does not create a booking link.

The id is checked first: an empty id or one longer than 256 characters gets `400 invalid_input` before any payment step and costs nothing. Whether the offer still exists is known only to Duffel, which Munition asks after the payment settled. If Duffel does not have it (an unknown id, or an offer it no longer serves, such as an expired one), the answer is `404 offer_not_found` with `paidCallId`, and the payment is kept: look up offers soon after the search.

Response of `GET /v1/flights/offers/{id}`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `id` | string | yes | The offer id. |
| `totalPrice` | string | yes | The total price. |
| `currencyCode` | string | yes | Its currency. |
| `validatingAirlineCodes` | array of strings | yes | The airlines selling the fare. |
| `itineraries` | array of objects | yes | As in a flight search, with each segment's `cabin` and `cabinMarketingName`, and the itinerary's `conditions`. |
| `baggageAllowance` | object | yes | `carryOn` and `checked` bag counts, when known. |
| `fareConditions` | object | yes | `changeable`, `refundable`, the change and refund penalties, and `supportedPassengerIdentityDocumentTypes`, when known. |
| `cabin` | string | no | `economy`, `premium_economy`, `business` or `first`. |
| `conditions` | object | yes | A `description` of the conditions, when Duffel gives one. |
| `searchedAt` | string | yes | When the details were fetched. |

## Booking links

Free and without payment: the server builds KAYAK and Kiwi.com search URLs from the route and dates, and calls no provider. The links start a new search; the traveler confirms passengers, cabin, availability and price on that site.

Body of `POST /v1/tools/flight-booking-links`:

| Field | Type | Required | Default | Limits and notes |
| --- | --- | --- | --- | --- |
| `origin` | string | yes | — | A 3-letter IATA code. |
| `destination` | string | yes | — | A 3-letter IATA code, different from `origin`. |
| `departureDate` | string | yes | — | `YYYY-MM-DD`, a real calendar date. |
| `returnDate` | string | no | — | `YYYY-MM-DD`, on or after `departureDate`. Leave it out for one way. |

Response of `POST /v1/tools/flight-booking-links`:

| Field | Type | Always present | Notes |
| --- | --- | --- | --- |
| `kind` | string | yes | Always `external_flight_search`. |
| `search` | object | yes | The route and dates, normalized. |
| `links` | array of objects | yes | Two links, each with `provider` (`kayak` or `kiwi`), `label` and `url`. |
| `notice` | string | yes | Says the links start a new search and reserve nothing. |

## Example

A round-trip search from San Francisco to Tokyo Narita. Called without payment, it answers `402` with the price in the `PAYMENT-REQUIRED` header; pay and send it again as in [Copy-paste examples](/docs/payments/examples).

```bash
curl -sS -i https://api.munition.io/v1/flights/search \
  -H 'Content-Type: application/json' \
  --data '{"origin":"SFO","destination":"NRT","departureDate":"2027-08-10","returnDate":"2027-08-21","adults":1,"travelClass":"ECONOMY","maxResults":10}'
```

Paid, it costs 0.05 USDC. A response of `POST /v1/flights/search` looks like this, plus its `run` object:

```json
{
  "results": [
    {
      "id": "off_example",
      "source": "flight_search",
      "totalPrice": "418.90",
      "currency": "USD",
      "airlineCodes": ["BA"],
      "itineraries": [
        {
          "duration": "PT10H15M",
          "numberOfStops": 0,
          "segments": [
            {
              "departure": { "airportCode": "SFO", "at": "2027-08-10T12:00:00" },
              "arrival": { "airportCode": "NRT", "at": "2027-08-11T15:00:00" },
              "carrierCode": "BA",
              "flightNumber": "284"
            }
          ]
        }
      ]
    }
  ],
  "meta": { "resultCount": 1, "searchedAt": "2026-11-03T12:00:00.000Z" }
}
```

When Duffel fails after payment, the x402 and MPP flight routes and the MCP flight tools keep the payment and answer `502 upstream_failed` with `paidCallId` (`404 offer_not_found` for an offer Duffel does not have). Send the same request again with the same `Idempotency-Key` to run it again without a second charge; with an MCP tool, call it again with the same arguments: see [Errors and refunds](/docs/payments/errors#when-payment-settles-but-the-service-fails).
