# AGENTS.md: Ktemia API

Instructions for coding agents (Claude Code, Codex, Cursor and others) that call the Ktemia API.

Ktemia is a travel search API. It searches and compares flights, hotels and car rentals across airlines, booking sites and rental companies. Each result names the seller, the price and a booking link. Ktemia compares; it does not issue tickets, take payment or hold reservations. The traveller books on the seller's site.

- Full reference: https://www.ktemia.com/docs/api/
- Getting started: https://www.ktemia.com/docs/getting-started/
- MCP server: https://www.ktemia.com/docs/mcp/
- Every endpoint as one plain-text file: https://www.ktemia.com/docs/api/llms.txt
- OpenAPI 3.1 spec: https://www.ktemia.com/openapi.json
- Changelog: https://www.ktemia.com/docs/changelog/
- Markdown version of any docs page: append `.md` to the URL without the trailing slash, e.g. https://www.ktemia.com/docs/api/flights/search.md
- Site index for LLMs: https://www.ktemia.com/llms.txt

## Setup

1. Get an API key at https://app.ktemia.com. The Free plan includes 100 API requests a month.
2. Store it in the environment as `KTEMIA_API_KEY`. Never print it, commit it, or put it in browser JavaScript. Call the API from a server.
3. Send it as the `X-API-Key` header on every request.

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

Base URL: `https://api.ktemia.com`. HTTPS only, JSON in and out, no version prefix.

## How every vertical works

A search returns a token, not results. Read results with the token, then expand one result into every seller's price.

1. Look up codes or ids first.
2. `POST /{vertical}/search` returns `searchToken` (valid for 60 minutes).
3. `GET /{vertical}/results?token=...` returns a page of results and a `nextToken` when there are more.
4. `GET /{vertical}/details?token=...&resultId=...` returns every seller's price and booking URL for one result.

| Vertical | Look up | Search | Results | Details | Extra |
|---|---|---|---|---|---|
| Flights | `GET /flights/airports`, `GET /flights/airlines` | `POST /flights/search` | `GET /flights/results` | `GET /flights/details` | |
| Hotels | `GET /hotels/locations` | `POST /hotels/search` | `GET /hotels/results` | `GET /hotels/details` | `GET /hotels/reviews` |
| Cars | `GET /cars/locations` | `POST /cars/search` | `GET /cars/results` | `GET /cars/details` | |

Required search fields:
- Flights: `origin`, `destination` (IATA airport or city codes from `/flights/airports`), `departureDate`. Add `returnDate` for a round trip, or send `legs` (2–6) instead for multi-city.
- Hotels: `location` (an id from `/hotels/locations`, not a place name), `checkin`, `checkout`.
- Cars: `pickupLocation` (an id from `/cars/locations`), `pickupDate`, `dropoffDate`.

## Rules

- **Ask, don't guess.** If a place or a date is missing or vague ("soon", "somewhere warm"), ask the user. Every call counts against their monthly quota.
- Dates are `YYYY-MM-DD` and cannot be in the past.
- If a lookup returns several matches (for example "Austin"), ask which one. Don't take the first.
- There is no `currency` field. Send `country` to pick the market; prices come back in that country's currency. Omitting it means the US market and USD.
- Filter to named sellers with ids from the results page: `airlines` (2-letter IATA codes) on flights, `providers` on hotels and cars, `agencies` on cars.
- Return each `providerUrl` to the user exactly as the API gave it.
- Ktemia compares prices. Don't tell the user anything was booked.

## Errors

Every error uses one envelope: `error.code` (stable, uppercase), `error.message` (safe to show), and `error.param` (the field at fault, when there is one). Unknown fields are rejected.

- `400`: malformed request (`MISSING_FIELD`, `TRIP_CONFLICT`, `TOO_FEW_LEGS`, `INVALID_ORIGIN`, `INVALID_LOCATION`, `LEGS_OUT_OF_ORDER`, `INVALID_SEARCH_TOKEN`). Fix the named field.
- `401`: `MISSING_API_KEY` or `INVALID_API_KEY`.
- `404`: `NO_RESULTS` (valid trip, nothing published) or `NO_MORE_RESULTS` (past the last page).
- `410`: `SEARCH_EXPIRED`. Start a new search; retrying will not help.
- `429`: two different causes, handled differently. `RATE_LIMIT_EXCEEDED` means too fast - honour `Retry-After` and continue. `QUOTA_EXCEEDED` means the month's allowance is gone - stop, tell the user, and do not retry. Retrying it will not succeed again until the next month.
- `502`: temporary upstream failure (`SEARCH_FAILED`, `DETAILS_FAILED`, `*_UNAVAILABLE`, `UPSTREAM_ERROR`). Retry the same request.

## Limits

Free: 100 requests a month at 2 requests per second. Pro: 20,000 a month at 20 requests per second. Business: 250,000 a month at 250 requests per second. The monthly quota is shared across every key on the account. See https://www.ktemia.com/pricing/.

Every call counts, including one that returns `404 NO_RESULTS`. Each search costs at least two calls (search, then results), and a lookup is another, so a single question answered end to end is typically three to five.

`GET /key` reports the plan, the rate limits, and how much of the month is left. It is the one endpoint that is **not metered**: checking costs nothing, and it keeps answering after the quota is spent, so it is how you diagnose a `QUOTA_EXCEEDED`. Reference: https://www.ktemia.com/docs/api/key/

```bash
curl "https://api.ktemia.com/key" -H "X-API-Key: $KTEMIA_API_KEY"
# -> {"plan": {"name": "free", "monthlyQuota": 100, ...},
#     "usage": {"used": 37, "remaining": 63, "scope": "account", ...}, "metered": false}
```

`usage.scope` of `account` means every key on the account spends the same allowance, so `remaining` is not this key's alone. Every metered response also carries `X-Quota-Limit`, `X-Quota-Used`, `X-RateLimit-Limit`, and `X-RateLimit-Remaining`, so you can track the budget without a separate call.

## Ready-made tools

### MCP server

If the user runs an MCP client (Cursor, Claude Code, Claude Desktop, Codex), the MCP server is usually less work than writing HTTP calls: it handles the search-then-page flow and the error envelope for you.

Install it by writing the client's config, not by running an install command. There are two equivalent packages; use whichever runtime the user already has. Each launcher fetches the package on first run.

- Node 20+: `npx -y @ktemia/mcp` (npm: `@ktemia/mcp`)
- Python 3.10+ with `uv`: `uvx ktemia-mcp` (PyPI: `ktemia-mcp`)

Both have the same seven tools and the same behaviour. The examples below use Node. For Python, replace the command `npx` with `uvx` and the args `["-y", "@ktemia/mcp"]` with `["ktemia-mcp"]`.

- Claude Code: `claude mcp add ktemia -e KTEMIA_API_KEY=your-key -- npx -y @ktemia/mcp` (Python: `... -- uvx ktemia-mcp`)
- Cursor, in `~/.cursor/mcp.json`; Claude Desktop, in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ktemia": {
      "command": "npx",
      "args": ["-y", "@ktemia/mcp"],
      "env": { "KTEMIA_API_KEY": "your-key" }
    }
  }
}
```

- Codex CLI, in `~/.codex/config.toml`:

```toml
[mcp_servers.ktemia]
command = "npx"
args = ["-y", "@ktemia/mcp"]
env = { KTEMIA_API_KEY = "your-key" }
```

Never put the user's key in a file that gets committed. Prefer `"${env:KTEMIA_API_KEY}"` in a project-level config and have the user export the key in their shell profile.

Seven read-only tools: `ktemia_key_status`, `ktemia_lookup`, `ktemia_search_flights`, `ktemia_search_hotels`, `ktemia_search_cars`, `ktemia_get_details`, `ktemia_get_hotel_reviews`. Each call is one metered API request except `ktemia_key_status`, which is free.

Paging works by calling the **same search tool** again with only `nextToken`. When `nextToken` is absent, that was the last page.

Docs: https://www.ktemia.com/docs/mcp/ · npm: https://www.npmjs.com/package/@ktemia/mcp · PyPI: https://pypi.org/project/ktemia-mcp/ · Source: https://github.com/Ktemiaa/ktemia-mcp

The hosted server at `mcp.ktemia.com` is not live. Do not configure a client with a `url` pointing at it.

### Other

- Agent skills for Claude Code, Codex and Cursor (flight, car and hotel search): https://github.com/Ktemiaa/ktemia-skills
  - Claude Code: `/plugin marketplace add Ktemiaa/ktemia-skills`, then `/plugin install ktemia@ktemia`
- Public Postman workspace with every endpoint and the docs examples: https://www.postman.com/ktemia-411711/ktemia-api/overview
- Context7 library: https://context7.com/websites/ktemia_api
