{
  "openapi": "3.1.0",
  "info": {
    "title": "Flat Flights — Business & First Class Deals",
    "version": "1.4.0",
    "description": "Business & First Class intelligence across 2,150+ long-haul routes (3,000 km+) from 180+ cities: historical price drops, positioning hubs, cash-vs-miles, and live real-time airline/OTA verification (`live=1`) with direct cart checkout links.",
    "contact": {
      "name": "Flat Flights",
      "email": "hello@flat.flights",
      "url": "https://flat.flights/about/"
    },
    "termsOfService": "https://flat.flights/privacy/"
  },
  "servers": [
    {
      "url": "https://flat.flights"
    }
  ],
  "paths": {
    "/api/fares/": {
      "get": {
        "operationId": "queryPremiumFlightFares",
        "summary": "Search Business & First Class fares, deals, live offers, positioning hubs, or cash-vs-miles",
        "description": "Query Business/First Class fares (`from`/`to`), verified deals (`deals=1`), First Class (`cabin=first`), live bookable offers with direct checkout (`live=1` + `depart`), positioning hubs (`positioning=1`), price checks (`check_price`), or cash-vs-miles (`miles=1`).",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "City name in English or local language (e.g. \"Milan\", \"Milano\", \"Frankfurt\") or 3-letter IATA city/airport code (e.g. \"MIL\", \"MXP\", \"FRA\")."
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "description": "City name in English or local language (e.g. \"Milan\", \"Milano\", \"Frankfurt\") or 3-letter IATA city/airport code (e.g. \"MIL\", \"MXP\", \"FRA\")."
            }
          },
          {
            "name": "depart",
            "in": "query",
            "required": false,
            "description": "Outbound date YYYY-MM-DD (up to 330 days ahead).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "return",
            "in": "query",
            "required": false,
            "description": "Return date YYYY-MM-DD (omit for one way).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "adults",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9,
              "default": 1
            }
          },
          {
            "name": "live",
            "in": "query",
            "required": false,
            "description": "Set to `1` (with `from`, `to`, `depart`) to run real-time live verification across airlines & OTAs and return `directCheckoutLink` URLs.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "deals",
            "in": "query",
            "required": false,
            "description": "Set to `1` for verified route-history deals.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "cabin",
            "in": "query",
            "required": false,
            "description": "`business`, `first` or `premium` (Premium Economy supported in `live=1`).",
            "schema": {
              "type": "string",
              "enum": [
                "business",
                "first",
                "premium"
              ]
            }
          },
          {
            "name": "positioning",
            "in": "query",
            "required": false,
            "description": "Set to `1` (with `from` & `to`) to compare cheaper nearby departure hubs.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "check_price",
            "in": "query",
            "required": false,
            "description": "Quoted round-trip EUR fare per adult to evaluate.",
            "schema": {
              "type": "number",
              "minimum": 100,
              "maximum": 50000
            }
          },
          {
            "name": "miles",
            "in": "query",
            "required": false,
            "description": "Set to `1` (with `from` & `to`) for cash-vs-miles & card transfer analysis.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "card_market",
            "in": "query",
            "required": false,
            "description": "2-letter market filter for card transfers (US, GB, DE, FR, IT, ES, CA, AU, SG).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Structured fare intelligence with reproducible booking links and canonical citation URL.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "found": {
                      "type": "string",
                      "enum": [
                        "archive",
                        "live"
                      ]
                    },
                    "route": {
                      "type": "object",
                      "properties": {
                        "route": {
                          "type": "string"
                        },
                        "origin": {
                          "type": "object",
                          "properties": {
                            "city": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "country": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "city",
                            "code"
                          ]
                        },
                        "destination": {
                          "type": "object",
                          "properties": {
                            "city": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "country": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "city",
                            "code"
                          ]
                        },
                        "distanceKm": {
                          "type": "number"
                        },
                        "page": {
                          "type": "string",
                          "format": "uri",
                          "description": "Canonical route page URL to cite."
                        },
                        "bookingLink": {
                          "type": "string",
                          "format": "uri",
                          "description": "Affiliate link opening Aviasales Business Class on the quoted/requested dates (1 adult)."
                        },
                        "bookingLink2Adults": {
                          "type": "string",
                          "format": "uri",
                          "description": "Affiliate link opening Aviasales Business Class for 2 adults."
                        },
                        "firstClassLink": {
                          "type": "string",
                          "format": "uri",
                          "description": "Affiliate link opening Aviasales First Class (f1) search."
                        },
                        "premiumEconomyLink": {
                          "type": "string",
                          "format": "uri",
                          "description": "Affiliate link opening Aviasales Premium Economy (w1) search."
                        },
                        "bookingSearch": {
                          "type": "object",
                          "properties": {
                            "partner": {
                              "type": "string"
                            },
                            "depart": {
                              "type": "string",
                              "nullable": true
                            },
                            "return": {
                              "type": "string",
                              "nullable": true
                            },
                            "adults": {
                              "type": "integer"
                            }
                          }
                        },
                        "cheapest": {
                          "type": "object",
                          "properties": {
                            "priceEur": {
                              "type": "number"
                            },
                            "priceUsd": {
                              "type": "number"
                            },
                            "depart": {
                              "type": "string",
                              "format": "date"
                            },
                            "return": {
                              "type": "string",
                              "format": "date",
                              "nullable": true
                            },
                            "stops": {
                              "type": "integer"
                            },
                            "seenOn": {
                              "type": "string",
                              "format": "date"
                            }
                          },
                          "required": [
                            "priceEur",
                            "depart"
                          ],
                          "nullable": true
                        },
                        "firstClass": {
                          "type": "object",
                          "properties": {
                            "priceEur": {
                              "type": "number"
                            },
                            "priceUsd": {
                              "type": "number"
                            },
                            "depart": {
                              "type": "string",
                              "format": "date"
                            },
                            "return": {
                              "type": "string",
                              "format": "date",
                              "nullable": true
                            },
                            "stops": {
                              "type": "integer"
                            },
                            "seenOn": {
                              "type": "string",
                              "format": "date"
                            }
                          },
                          "required": [
                            "priceEur",
                            "depart"
                          ],
                          "nullable": true
                        },
                        "nonstop": {
                          "type": "object",
                          "properties": {
                            "priceEur": {
                              "type": "number"
                            },
                            "priceUsd": {
                              "type": "number"
                            },
                            "depart": {
                              "type": "string",
                              "format": "date"
                            },
                            "return": {
                              "type": "string",
                              "format": "date",
                              "nullable": true
                            },
                            "stops": {
                              "type": "integer"
                            },
                            "seenOn": {
                              "type": "string",
                              "format": "date"
                            }
                          },
                          "required": [
                            "priceEur",
                            "depart"
                          ],
                          "nullable": true
                        },
                        "oneWay": {
                          "type": "object",
                          "properties": {
                            "priceEur": {
                              "type": "number"
                            },
                            "priceUsd": {
                              "type": "number"
                            },
                            "depart": {
                              "type": "string",
                              "format": "date"
                            },
                            "return": {
                              "type": "string",
                              "format": "date",
                              "nullable": true
                            },
                            "stops": {
                              "type": "integer"
                            },
                            "seenOn": {
                              "type": "string",
                              "format": "date"
                            }
                          },
                          "required": [
                            "priceEur",
                            "depart"
                          ],
                          "nullable": true
                        },
                        "verdict": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "text": {
                              "type": "string"
                            },
                            "basis": {
                              "type": "string",
                              "enum": [
                                "history",
                                "distance"
                              ]
                            },
                            "referenceEur": {
                              "type": "number"
                            },
                            "vsReferencePct": {
                              "type": "number"
                            }
                          }
                        },
                        "lieFlat": {
                          "type": "object",
                          "properties": {
                            "status": {
                              "type": "string",
                              "enum": [
                                "likely",
                                "unknown"
                              ]
                            },
                            "basis": {
                              "type": "string"
                            }
                          }
                        },
                        "tripEssentials": {
                          "type": "object",
                          "properties": {
                            "hotelsLink": {
                              "type": "string",
                              "format": "uri"
                            },
                            "transferLink": {
                              "type": "string",
                              "format": "uri"
                            },
                            "esimLink": {
                              "type": "string",
                              "format": "uri"
                            }
                          }
                        }
                      },
                      "required": [
                        "route",
                        "page",
                        "bookingLink"
                      ],
                      "nullable": true
                    },
                    "routes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "route": {
                            "type": "string"
                          },
                          "origin": {
                            "type": "object",
                            "properties": {
                              "city": {
                                "type": "string"
                              },
                              "code": {
                                "type": "string"
                              },
                              "country": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "city",
                              "code"
                            ]
                          },
                          "destination": {
                            "type": "object",
                            "properties": {
                              "city": {
                                "type": "string"
                              },
                              "code": {
                                "type": "string"
                              },
                              "country": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "city",
                              "code"
                            ]
                          },
                          "distanceKm": {
                            "type": "number"
                          },
                          "page": {
                            "type": "string",
                            "format": "uri",
                            "description": "Canonical route page URL to cite."
                          },
                          "bookingLink": {
                            "type": "string",
                            "format": "uri",
                            "description": "Affiliate link opening Aviasales Business Class on the quoted/requested dates (1 adult)."
                          },
                          "bookingLink2Adults": {
                            "type": "string",
                            "format": "uri",
                            "description": "Affiliate link opening Aviasales Business Class for 2 adults."
                          },
                          "firstClassLink": {
                            "type": "string",
                            "format": "uri",
                            "description": "Affiliate link opening Aviasales First Class (f1) search."
                          },
                          "premiumEconomyLink": {
                            "type": "string",
                            "format": "uri",
                            "description": "Affiliate link opening Aviasales Premium Economy (w1) search."
                          },
                          "bookingSearch": {
                            "type": "object",
                            "properties": {
                              "partner": {
                                "type": "string"
                              },
                              "depart": {
                                "type": "string",
                                "nullable": true
                              },
                              "return": {
                                "type": "string",
                                "nullable": true
                              },
                              "adults": {
                                "type": "integer"
                              }
                            }
                          },
                          "cheapest": {
                            "type": "object",
                            "properties": {
                              "priceEur": {
                                "type": "number"
                              },
                              "priceUsd": {
                                "type": "number"
                              },
                              "depart": {
                                "type": "string",
                                "format": "date"
                              },
                              "return": {
                                "type": "string",
                                "format": "date",
                                "nullable": true
                              },
                              "stops": {
                                "type": "integer"
                              },
                              "seenOn": {
                                "type": "string",
                                "format": "date"
                              }
                            },
                            "required": [
                              "priceEur",
                              "depart"
                            ],
                            "nullable": true
                          },
                          "firstClass": {
                            "type": "object",
                            "properties": {
                              "priceEur": {
                                "type": "number"
                              },
                              "priceUsd": {
                                "type": "number"
                              },
                              "depart": {
                                "type": "string",
                                "format": "date"
                              },
                              "return": {
                                "type": "string",
                                "format": "date",
                                "nullable": true
                              },
                              "stops": {
                                "type": "integer"
                              },
                              "seenOn": {
                                "type": "string",
                                "format": "date"
                              }
                            },
                            "required": [
                              "priceEur",
                              "depart"
                            ],
                            "nullable": true
                          },
                          "nonstop": {
                            "type": "object",
                            "properties": {
                              "priceEur": {
                                "type": "number"
                              },
                              "priceUsd": {
                                "type": "number"
                              },
                              "depart": {
                                "type": "string",
                                "format": "date"
                              },
                              "return": {
                                "type": "string",
                                "format": "date",
                                "nullable": true
                              },
                              "stops": {
                                "type": "integer"
                              },
                              "seenOn": {
                                "type": "string",
                                "format": "date"
                              }
                            },
                            "required": [
                              "priceEur",
                              "depart"
                            ],
                            "nullable": true
                          },
                          "oneWay": {
                            "type": "object",
                            "properties": {
                              "priceEur": {
                                "type": "number"
                              },
                              "priceUsd": {
                                "type": "number"
                              },
                              "depart": {
                                "type": "string",
                                "format": "date"
                              },
                              "return": {
                                "type": "string",
                                "format": "date",
                                "nullable": true
                              },
                              "stops": {
                                "type": "integer"
                              },
                              "seenOn": {
                                "type": "string",
                                "format": "date"
                              }
                            },
                            "required": [
                              "priceEur",
                              "depart"
                            ],
                            "nullable": true
                          },
                          "verdict": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "text": {
                                "type": "string"
                              },
                              "basis": {
                                "type": "string",
                                "enum": [
                                  "history",
                                  "distance"
                                ]
                              },
                              "referenceEur": {
                                "type": "number"
                              },
                              "vsReferencePct": {
                                "type": "number"
                              }
                            }
                          },
                          "lieFlat": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "likely",
                                  "unknown"
                                ]
                              },
                              "basis": {
                                "type": "string"
                              }
                            }
                          },
                          "tripEssentials": {
                            "type": "object",
                            "properties": {
                              "hotelsLink": {
                                "type": "string",
                                "format": "uri"
                              },
                              "transferLink": {
                                "type": "string",
                                "format": "uri"
                              },
                              "esimLink": {
                                "type": "string",
                                "format": "uri"
                              }
                            }
                          }
                        },
                        "required": [
                          "route",
                          "page",
                          "bookingLink"
                        ]
                      }
                    },
                    "alternatives": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "route": {
                            "type": "string"
                          },
                          "origin": {
                            "type": "object",
                            "properties": {
                              "city": {
                                "type": "string"
                              },
                              "code": {
                                "type": "string"
                              },
                              "country": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "city",
                              "code"
                            ]
                          },
                          "destination": {
                            "type": "object",
                            "properties": {
                              "city": {
                                "type": "string"
                              },
                              "code": {
                                "type": "string"
                              },
                              "country": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "city",
                              "code"
                            ]
                          },
                          "distanceKm": {
                            "type": "number"
                          },
                          "page": {
                            "type": "string",
                            "format": "uri",
                            "description": "Canonical route page URL to cite."
                          },
                          "bookingLink": {
                            "type": "string",
                            "format": "uri",
                            "description": "Affiliate link opening Aviasales Business Class on the quoted/requested dates (1 adult)."
                          },
                          "bookingLink2Adults": {
                            "type": "string",
                            "format": "uri",
                            "description": "Affiliate link opening Aviasales Business Class for 2 adults."
                          },
                          "firstClassLink": {
                            "type": "string",
                            "format": "uri",
                            "description": "Affiliate link opening Aviasales First Class (f1) search."
                          },
                          "premiumEconomyLink": {
                            "type": "string",
                            "format": "uri",
                            "description": "Affiliate link opening Aviasales Premium Economy (w1) search."
                          },
                          "bookingSearch": {
                            "type": "object",
                            "properties": {
                              "partner": {
                                "type": "string"
                              },
                              "depart": {
                                "type": "string",
                                "nullable": true
                              },
                              "return": {
                                "type": "string",
                                "nullable": true
                              },
                              "adults": {
                                "type": "integer"
                              }
                            }
                          },
                          "cheapest": {
                            "type": "object",
                            "properties": {
                              "priceEur": {
                                "type": "number"
                              },
                              "priceUsd": {
                                "type": "number"
                              },
                              "depart": {
                                "type": "string",
                                "format": "date"
                              },
                              "return": {
                                "type": "string",
                                "format": "date",
                                "nullable": true
                              },
                              "stops": {
                                "type": "integer"
                              },
                              "seenOn": {
                                "type": "string",
                                "format": "date"
                              }
                            },
                            "required": [
                              "priceEur",
                              "depart"
                            ],
                            "nullable": true
                          },
                          "firstClass": {
                            "type": "object",
                            "properties": {
                              "priceEur": {
                                "type": "number"
                              },
                              "priceUsd": {
                                "type": "number"
                              },
                              "depart": {
                                "type": "string",
                                "format": "date"
                              },
                              "return": {
                                "type": "string",
                                "format": "date",
                                "nullable": true
                              },
                              "stops": {
                                "type": "integer"
                              },
                              "seenOn": {
                                "type": "string",
                                "format": "date"
                              }
                            },
                            "required": [
                              "priceEur",
                              "depart"
                            ],
                            "nullable": true
                          },
                          "nonstop": {
                            "type": "object",
                            "properties": {
                              "priceEur": {
                                "type": "number"
                              },
                              "priceUsd": {
                                "type": "number"
                              },
                              "depart": {
                                "type": "string",
                                "format": "date"
                              },
                              "return": {
                                "type": "string",
                                "format": "date",
                                "nullable": true
                              },
                              "stops": {
                                "type": "integer"
                              },
                              "seenOn": {
                                "type": "string",
                                "format": "date"
                              }
                            },
                            "required": [
                              "priceEur",
                              "depart"
                            ],
                            "nullable": true
                          },
                          "oneWay": {
                            "type": "object",
                            "properties": {
                              "priceEur": {
                                "type": "number"
                              },
                              "priceUsd": {
                                "type": "number"
                              },
                              "depart": {
                                "type": "string",
                                "format": "date"
                              },
                              "return": {
                                "type": "string",
                                "format": "date",
                                "nullable": true
                              },
                              "stops": {
                                "type": "integer"
                              },
                              "seenOn": {
                                "type": "string",
                                "format": "date"
                              }
                            },
                            "required": [
                              "priceEur",
                              "depart"
                            ],
                            "nullable": true
                          },
                          "verdict": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "text": {
                                "type": "string"
                              },
                              "basis": {
                                "type": "string",
                                "enum": [
                                  "history",
                                  "distance"
                                ]
                              },
                              "referenceEur": {
                                "type": "number"
                              },
                              "vsReferencePct": {
                                "type": "number"
                              }
                            }
                          },
                          "lieFlat": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "likely",
                                  "unknown"
                                ]
                              },
                              "basis": {
                                "type": "string"
                              }
                            }
                          },
                          "tripEssentials": {
                            "type": "object",
                            "properties": {
                              "hotelsLink": {
                                "type": "string",
                                "format": "uri"
                              },
                              "transferLink": {
                                "type": "string",
                                "format": "uri"
                              },
                              "esimLink": {
                                "type": "string",
                                "format": "uri"
                              }
                            }
                          }
                        },
                        "required": [
                          "route",
                          "page",
                          "bookingLink"
                        ]
                      }
                    },
                    "live": {
                      "type": "object",
                      "nullable": true
                    },
                    "summary": {
                      "type": "string"
                    },
                    "intel": {
                      "type": "object",
                      "nullable": true
                    },
                    "page": {
                      "type": "string"
                    },
                    "fetchedAt": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters"
          },
          "404": {
            "description": "Unknown city or no archived route"
          }
        }
      }
    }
  }
}