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.
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:
{
"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.