# Introduction A flights API for search and compare. Describe a trip and get the providers who can sell it, with prices. Booking stays with the provider. Ktemia is a travel search API. You describe a trip for a person. The response is the providers who can sell it: airlines, agencies, and other sellers, with prices you can compare. The API does not issue a ticket, take payment, or hold a reservation. When you open an offer, the response includes that provider’s URL. The person books on the provider’s site. ## Base URL Every request goes to `https://api.ktemia.com`. There is no version prefix. The API is HTTPS only. Send JSON, and you get JSON back. A search is `POST` with a body. A read that follows a search is `GET` with query parameters. ## Providers Each offer names the provider and the price, so you can show a person the choices side by side. The booking link opens that provider’s site with the trip filled in. Leave the URL as the API returned it. Look up an airport or city code with [Search airports](https://www.ktemia.com/docs/api/flights/airports/), then start a flight search at [Search flights](https://www.ktemia.com/docs/api/flights/search/). For a car hire, look up a place with [Search locations](https://www.ktemia.com/docs/api/cars/locations/), then start at [Search cars](https://www.ktemia.com/docs/api/cars/search/). Authentication, errors, and pagination are the sections below. They apply to every call. ## Read more How Ktemia compares with other travel APIs, by who can get a key: [best travel API in 2026](https://www.ktemia.com/blog/best-travel-api/). Why a search API is not a GDS or a booking engine: [GDS vs booking engine vs a search API](https://www.ktemia.com/blog/search-api-vs-gds-booking-engine/). Search flights from Claude Code, Cursor, or Codex with the open-source [Ktemia flight search skill](https://github.com/Ktemiaa/ktemia-flights-skill): `/plugin marketplace add Ktemiaa/ktemia-flights-skill`, then `/plugin install ktemia@ktemia`. ## Authentication Every request requires an API key. Create one in the dashboard, then send it on every call. ### The header Pass `X-API-Key: `. A missing key answers `401 MISSING_API_KEY`. A bad key answers `401 INVALID_API_KEY`. Both include `{"success": false, "error": {"code", "message"}, "data": null}`. Keys are secrets. Keep them in an environment variable on a server. The playground on this site keeps a key in this browser tab so you can try a call. Do not put a key in the JavaScript of your own app. ### HTTPS only The API is HTTPS only. Call it from your server. This site’s playground is allowed to call it from the browser; other websites are not. ## Errors Success responses are the JSON shown on each endpoint. Errors use one shape: a missing key, a bad body, an empty search, an expired token. ### The envelope `error.code` is stable and uppercase. `error.message` is safe to show. `error.param` is the field to highlight when the input was wrong (`departureDate`, `legs[1].date`, `airlines[0]`). It is omitted when the failure is not about a field. Unknown fields are rejected. The response names the field in `error.param`. ### Status codes `400` — the request is malformed (`MISSING_FIELD`, `TRIP_CONFLICT`, `INVALID_ORIGIN`, `INVALID_LOCATION`, `LEGS_OUT_OF_ORDER`, `INVALID_SEARCH_TOKEN`, …). `401` — missing or invalid API key. `404` — `NO_RESULTS` on search (the trip is valid, nothing published), or `NO_MORE_RESULTS` on a page past the end. `410` — `SEARCH_EXPIRED`. The token was valid and is now gone. Start a new search; retrying this one will not help. `429` — rate limit or a temporary block after repeated auth failures. Honour `Retry-After`. `502` — `SEARCH_FAILED`, `DETAILS_FAILED`, `AIRPORTS_UNAVAILABLE`, `LOCATIONS_UNAVAILABLE`, or `UPSTREAM_ERROR`. Temporary. Retry the same request. ## Pagination Each search is fixed for 60 minutes. `/flights/results` and `/cars/results` read the next page of that search. Page 2 does not repeat page 1. ### Tokens, not page numbers `/flights/search` and `/cars/search` return `searchToken` for page 1. Each results response that is not the last page includes `nextToken`. Send that as the `token` query parameter to get the next 20. You cannot request a page by number. A token that is not valid answers `400 INVALID_SEARCH_TOKEN`. A token that has expired answers `410 SEARCH_EXPIRED`. Start a new search. ### totalResults `totalResults` is the number of itineraries in the search. `hasMore` is true when another page exists. The last page omits `nextToken`. Requesting a page after that returns `404 NO_MORE_RESULTS`. Docs: https://www.ktemia.com/docs/api/ ## Flights `GET /flights/airports?query=` returns airport and city codes. Send `code` as origin or destination. `allAirports: true` is a city code such as NYC or LON. `POST /flights/search` starts a search and returns a searchToken. It does not return offers. One-way is origin, destination, and departureDate. Round trip adds returnDate. Multi-city sends `legs` (2 to 6) and does not send the flat fields in the same body. `GET /flights/results?token=` returns a page of 20 offers. Use nextToken for the following page. `GET /flights/details?token=&resultId=` returns one itinerary, including each provider booking URL. ## Skill Claude Code, Cursor, and Codex can search flights with the Ktemia flight search skill. https://github.com/Ktemiaa/ktemia-flights-skill Install in Claude Code: ``` /plugin marketplace add Ktemiaa/ktemia-flights-skill /plugin install ktemia@ktemia ``` Set `KTEMIA_API_KEY` in the environment. The skill looks up airport codes, asks when a name matches several cities, and returns each seller’s booking URL. It does not book tickets. Do not guess origin, destination, or dates. ## Cars `GET /cars/locations?query=` returns pickup ids. Send `locationId` as pickupLocation. `POST /cars/search` starts a search and returns a searchToken. It does not return cars. Required fields are pickupLocation, pickupDate, and dropoffDate. `GET /cars/results?token=` returns a page of 20 cars. Use nextToken for the following page. `GET /cars/details?token=&resultId=` returns one car, including each provider booking URL. Each endpoint page lists every parameter, the allowed values, and a captured example. https://www.ktemia.com/docs/api/flights/search/ https://www.ktemia.com/docs/api/cars/search/