Search recorded prices. Read every result state.

Make your first search

Send an exact departure date and two three-letter IATA codes. The API defaults to one adult, economy, EUR, and the DE market. It reads stored observations; it does not start an airline search.

1. Obtain a search key from the deployment operator, or configure FLIGHT_API_KEY when running the project locally.
2. Send the request from your server. Keep the key out of browser code. Replace the sample departure date with a date you want to query.
3. Check complete and coverage before presenting any offer.

curl -X POST "https://itindb.dev/api/v1/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_SEARCH_KEY" \
  -d '{"origin":"BER","destination":"BCN","departure_date":"2026-11-05"}'

For a local deployment, replace the base URL with http://localhost:5173. An unconfigured source set returns an empty, incomplete result.

{
  "search": {
    "origin": "BER", "destination": "BCN",
    "departure_date": "2026-11-05", "adults": 1,
    "cabin": "economy", "currency": "EUR", "market": "DE"
  },
  "data_mode": "observations",
  "live": false,
  "complete": true,
  "coverage": [{
    "source_id": "sample_source", "status": "ok",
    "observed_at": "2026-10-07T09:15:00Z",
    "error_code": null
  }],
  "offers": [{
    "id": "sample-offer-1", "source_id": "sample_source",
    "source_offer_id": "BER-BCN-001",
    "observed_at": "2026-10-07T09:15:00Z",
    "price": {
      "total_minor": 12900, "currency": "EUR",
      "passengers": 1, "status": "observed"
    },
    "itinerary": {
      "airline": "Example Air", "flight_numbers": ["EX 123"],
      "departure_local_date": "2026-11-05",
      "departure_at": "2026-11-05T07:30:00.000Z",
      "arrival_at": "2026-11-05T09:45:00.000Z"
    },
    "baggage": "unknown", "booking_url": null
  }]
}

Authentication

Pass the search key in X-API-Key for POST /api/v1/search. The deployment currently has one configured search credential rather than individual developer accounts. There is no signup or key dashboard yet.

A missing or invalid key returns HTTP 401 with UNAUTHORIZED. A deployment with no configured key returns HTTP 503 with SERVICE_NOT_CONFIGURED. Source registration and ingestion use a separate operator credential, described in the operator guide.

Read a result

Complete coverage describes the configured source set, not every airline. Prices use minor currency units: 12900 with EUR means €129.00. The total covers the searched adult party and mandatory taxes and fees. Optional seats and baggage can cost extra.

Understand every result state

Always read coverage with offers. An empty array alone cannot establish that no flights exist.

{
  "data_mode": "observations",
  "live": false,
  "complete": false,
  "coverage": [],
  "offers": []
}

Fare fields and limits

Each offer contains its source, observation time, total price, airline, flight numbers, departure and arrival timestamps, baggage state, and a booking URL when supplied. A booking URL is a handoff, not a guarantee of the same fare at checkout.

Timestamps in actual API responses are normalized to UTC. The API does not yet return airport time zones or separate local wall times. Do not label the returned timestamp as local time.

Searches are one-way, exact-date, and adult-only. Return journeys, fare rules, live repricing, and booking are outside this version. The synthetic collection endpoints are test-only and do not provide airline quotes.

Handle errors

Errors use { "error": { "code": "...", "message": "..." } }. Treat HTTP status as the category and code as the machine-readable reason.

A successful HTTP response can still have complete: false. Handle it as a data coverage state rather than an HTTP failure.

Exact schemas

Use the OpenAPI specification for request and response schemas and llms.txt for a concise integration summary. The raw specification also includes operator and synthetic test endpoints.