# Flight search

> Search and compare flights from Claude Code, Codex, or Cursor with the Ktemia flight search API: one-way, round trip, or multi-city. Ask in plain language, and the agent looks up airport codes, asks for anything missing instead of guessing, and returns fares from each seller with booking links. - Website: https://www.ktemia.com/ - API docs: https://www.ktemia.com/docs/api/ - Search flights reference: https://www.ktemia.com/docs/api/flights/search/ - Guide: https://www.ktemia.com/blog/flight-search-api/

- Skill: `contact/flight-search` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add contact/flight-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/contact/flight-search/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: any agent that reads SKILL.md (Claude Code, Claude.ai, Cursor, Codex, Windsurf, 60+ more)
- Category: Web & Frontend
- Author: ktemia (https://skillmd.com/u/ktemia)
- Updated: 2026-11-07
- Page: https://skillmd.com/skills/contact/flight-search

---


# Flight search with the Ktemia API

Ktemia is a flight search API. It compares fares and returns each seller's booking link. It does not book tickets: the traveller books on the seller's site.

API reference: https://www.ktemia.com/docs/api/

## Before you call anything

1. You need `KTEMIA_API_KEY` in the environment. If it is missing, tell the user to create a key (https://www.ktemia.com/docs/api/#authentication) and export it. Never print the key or put it in code you write for a browser.
2. You need three things from the user: where from, where to, and the departure date. For a round trip, also the return date.
3. **Do not guess.** If any of these is missing or vague ("soon", "somewhere warm", "Europe"), ask. Every API call counts against the user's monthly quota, so a guessed search wastes it.
4. Dates are `YYYY-MM-DD` and must be today or later. Resolve "next Friday" into a date and confirm it with the user if there is any doubt.

## Workflow

Use the bundled script `scripts/ktemia.py` in this skill's directory. It needs only Python 3, no packages. Every command prints JSON.

### 1. Turn place names into codes

`origin` and `destination` are IATA airport or city codes (`LHR`, `JFK`, or city codes such as `LON`, `NYC`). If the user gave a name, look it up:

```bash
python3 scripts/ktemia.py airports "Lisbon"
```

- Use `code` from the match the user meant. `allAirports: true` means the code covers every airport in that city.
- If several places match (for example `austin` returns Austin, Texas; Austin, Nevada; and Austin-Straubel in Green Bay), **ask which one**. Do not take the first match.

### 2. Start the search

One-way or round trip:

```bash
python3 scripts/ktemia.py search --origin LIS --destination LHR --date 2027-03-15
python3 scripts/ktemia.py search --origin JFK --destination CDG --date 2027-03-10 --return 2027-03-17 --adults 2 --max-stops 1 --sort price
```

Multi-city (legs in travel order, at least two):

```bash
python3 scripts/ktemia.py search --leg LIS:BCN:2027-04-02 --leg BCN:FCO:2027-04-06 --leg FCO:LIS:2027-04-10
```

Other options: `--cabin economy|premiumEconomy|business|first`, `--children N`, `--max-price N` (per person), `--airlines NH,JL`, `--country GB` (market, which sets the currency).

The search returns a `searchToken`, valid for 60 minutes. It does not return flights.

### 3. Read results

```bash
python3 scripts/ktemia.py results <searchToken>
```

Up to 20 itineraries per page, already sorted. Show the user a short list: times, stops, duration, seller, and price. `price` is per person; `totalPrice` covers all travellers. If `nextToken` is present and the user wants more, call `results <nextToken>`.

### 4. Booking links for one itinerary

```bash
python3 scripts/ktemia.py details <searchToken> <flight id>
```

Each fare includes `providerUrl`, the seller's booking page. Give the user the link as returned; do not edit the query string. Make clear they book on the seller's site, and that prices can change after the search.

## Errors

The script prints the API error and exits non-zero. Common codes:

- `MISSING_FIELD` / `INVALID_REQUEST`: ask the user for the field in `param`, or fix the value.
- `DATE_IN_PAST`: ask for a future date.
- `NO_RESULTS` (404): nothing published for that route and date. Suggest nearby dates or airports, and ask before searching again.
- `SEARCH_EXPIRED` (410): the 60-minute token is gone. Start a new search.
- `MISSING_API_KEY` / `INVALID_API_KEY` (401): the key is missing or wrong.
- `QUOTA_EXCEEDED` / `RATE_LIMIT_EXCEEDED` (429): stop and tell the user. Do not retry in a loop.

Full list: https://www.ktemia.com/docs/api/#errors

## Without Python

The same calls with curl:

```bash
curl "https://api.ktemia.com/flights/airports?query=Lisbon" -H "X-API-Key: $KTEMIA_API_KEY"

curl https://api.ktemia.com/flights/search \
  -H "X-API-Key: $KTEMIA_API_KEY" -H "Content-Type: application/json" \
  -d '{"origin": "LIS", "destination": "LHR", "departureDate": "2027-03-15"}'

curl "https://api.ktemia.com/flights/results?token=$TOKEN" -H "X-API-Key: $KTEMIA_API_KEY"
curl "https://api.ktemia.com/flights/details?token=$TOKEN&resultId=$ID" -H "X-API-Key: $KTEMIA_API_KEY"
```

