{
  "openapi": "3.0.0",
  "info": {
    "title": "FlightSeatMap API",
    "description": "API for searching flight seat maps, getting seat recommendations, and exploring airline and airport data on FlightSeatMap.com.",
    "version": "1.0.0"
  },
  "x-service-info": {
    "categories": ["travel", "data"],
    "docs": {
      "homepage": "https://flightseatmap.com",
      "apiReference": "https://flightseatmap.com/openapi.json",
      "llms": "https://flightseatmap.com/llms.txt"
    }
  },
  "servers": [
    {
      "url": "https://flightseatmap.com"
    }
  ],
  "paths": {
    "/api/chatgpt/search_flights": {
      "get": {
        "operationId": "searchFlights",
        "summary": "Search for flights with seat maps",
        "description": "Search for flights by flight number, origin/destination airport IATA codes, or airline name/IATA code. Returns a list of flights with basic seatmap info.",
        "parameters": [
          {
            "name": "flight_number",
            "in": "query",
            "description": "Flight number (e.g. AA123, BA456, EK625). Letters followed by digits.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "origin",
            "in": "query",
            "description": "Origin airport IATA code (e.g. JFK, LHR, DXB)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "destination",
            "in": "query",
            "description": "Destination airport IATA code (e.g. LAX, CDG, SIN)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "airline",
            "in": "query",
            "description": "Airline name or IATA code (e.g. 'Emirates', 'EK', 'British Airways', 'BA')",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching flights",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer",
                      "description": "Number of results"
                    },
                    "flights": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FlightSummary"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/chatgpt/seatmap/{flight_number}": {
      "get": {
        "operationId": "getSeatmap",
        "summary": "Get detailed seat map for a flight",
        "description": "Returns the full seat map for a specific flight including all seats, their cabin class, availability status, and features (window, aisle, exit row, etc.).",
        "parameters": [
          {
            "name": "flight_number",
            "in": "path",
            "description": "Flight number (e.g. AA123, BA456)",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "flight_date",
            "in": "query",
            "description": "Flight date in YYYY-MM-DD format for date-specific seat availability",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed seat map",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SeatmapDetail"
                }
              }
            }
          },
          "400": {
            "description": "Invalid flight number format"
          },
          "404": {
            "description": "Flight not found"
          }
        }
      }
    },
    "/api/chatgpt/seat_recommendations/{flight_number}": {
      "get": {
        "operationId": "getSeatRecommendations",
        "summary": "Get seat recommendations based on preferences",
        "description": "Returns recommended available seats for a flight based on the user's seating preference (window, aisle, extra legroom, exit row, bulkhead, front of cabin, quiet zone).",
        "parameters": [
          {
            "name": "flight_number",
            "in": "path",
            "description": "Flight number (e.g. AA123, BA456)",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "preference",
            "in": "query",
            "description": "Seat preference type",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["window", "aisle", "extra_legroom", "exit_row", "bulkhead", "front", "quiet"],
              "default": "window"
            }
          },
          {
            "name": "cabin_class",
            "in": "query",
            "description": "Cabin class filter",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Seat recommendations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "flightNumber": { "type": "string" },
                    "airline": { "type": "string" },
                    "aircraft": { "type": "string" },
                    "preference": { "type": "string" },
                    "cabinClass": { "type": "string" },
                    "totalAvailableSeats": { "type": "integer" },
                    "recommendedSeats": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Seat" }
                    },
                    "url": { "type": "string", "description": "Link to view interactive seat map on FlightSeatMap.com" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Flight not found"
          }
        }
      }
    },
    "/api/chatgpt/airlines": {
      "get": {
        "operationId": "searchAirlines",
        "summary": "Search airlines",
        "description": "Search for airlines by name or IATA code. Returns airline info including fleet size and ratings.",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "description": "Search term - airline name or IATA code (e.g. 'Emirates', 'BA', 'Delta')",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (1-50, default 25)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of airlines",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "airlines": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Airline" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/chatgpt/airlines/{iata}": {
      "get": {
        "operationId": "getAirlineDetail",
        "summary": "Get airline details with fleet and routes",
        "description": "Get detailed information about an airline including its fleet of aircraft, routes, ratings, and seat map links.",
        "parameters": [
          {
            "name": "iata",
            "in": "path",
            "description": "Airline IATA code (e.g. AA, BA, EK)",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Airline details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AirlineDetail" }
              }
            }
          },
          "404": {
            "description": "Airline not found"
          }
        }
      }
    },
    "/api/chatgpt/airports": {
      "get": {
        "operationId": "searchAirports",
        "summary": "Search airports",
        "description": "Search for airports by name, city, IATA code, or country.",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "description": "Search term - airport name, city, or IATA code (e.g. 'Heathrow', 'London', 'JFK')",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "description": "Filter by country name",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results (1-50, default 25)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of airports",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "airports": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Airport" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/chatgpt/routes": {
      "get": {
        "operationId": "searchRoutes",
        "summary": "Find flight routes between airports",
        "description": "Find flights operating between airports. Filter by origin, destination, and/or airline.",
        "parameters": [
          {
            "name": "origin",
            "in": "query",
            "description": "Origin airport IATA code (e.g. JFK, LHR)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "destination",
            "in": "query",
            "description": "Destination airport IATA code (e.g. LAX, CDG)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "airline_iata",
            "in": "query",
            "description": "Airline IATA code to filter routes (e.g. AA, BA)",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of routes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer" },
                    "routes": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/FlightSummary" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1": {
      "get": {
        "operationId": "getPaidApiTerms",
        "summary": "Payment terms for the machine-payable API",
        "description": "Always returns 402 with x402 payment requirements. Agents read the price, network and accepted asset here before calling a paid route.",
        "x-payment-info": {
          "intent": "charge",
          "method": "stripe",
          "amount": "299",
          "currency": "USD",
          "description": "Price list for the v1 machine-payable API.",
          "offers": [
            {
              "intent": "charge",
              "method": "stripe",
              "amount": "2990000",
              "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              "description": "USDC on Base over x402, settled through Stripe."
            }
          ]
        },
        "responses": {
          "402": {
            "description": "Payment required. The body is an x402 PaymentRequirementsResponse."
          }
        }
      }
    },
    "/api/v1/seatmaps/{flight_number}": {
      "get": {
        "operationId": "getPaidSeatmap",
        "summary": "Buy one live seat map (x402)",
        "description": "Pay-per-call live seat map, no account needed. Call without an X-PAYMENT header to get the 402 payment requirements, then retry with a signed x402 payment to get the data.",
        "parameters": [
          {
            "name": "flight_number",
            "in": "path",
            "description": "Flight number (e.g. AA123, BA456)",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "date",
            "in": "query",
            "description": "Flight date in YYYY-MM-DD format. Defaults to today.",
            "required": false,
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "X-PAYMENT",
            "in": "header",
            "description": "Base64-encoded x402 PaymentPayload.",
            "required": false,
            "schema": { "type": "string" }
          }
        ],
        "x-payment-info": {
          "intent": "charge",
          "method": "stripe",
          "amount": "299",
          "currency": "USD",
          "description": "One live aircraft seat map: cabin layout, seat features and availability.",
          "offers": [
            {
              "intent": "charge",
              "method": "stripe",
              "amount": "2990000",
              "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              "description": "USDC on Base over x402, settled through Stripe."
            }
          ]
        },
        "responses": {
          "200": {
            "description": "Seat map. X-PAYMENT-RESPONSE carries the settlement receipt.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SeatmapDetail" }
              }
            }
          },
          "400": { "description": "Invalid date" },
          "402": { "description": "Payment required, or the payment failed verification" },
          "404": {
            "description": "No seat map available for this flight. Payment is not settled."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FlightSummary": {
        "type": "object",
        "properties": {
          "flightNumber": { "type": "string", "description": "Flight number (e.g. AA123)" },
          "airline": { "type": "string", "description": "Airline name" },
          "airlineCode": { "type": "string", "description": "Airline IATA code" },
          "airlineLogo": { "type": "string", "description": "URL to airline logo" },
          "origin": { "type": "string", "description": "Origin airport IATA code" },
          "originCity": { "type": "string", "description": "Origin city name" },
          "originAirport": { "type": "string", "description": "Origin airport name" },
          "destination": { "type": "string", "description": "Destination airport IATA code" },
          "destinationCity": { "type": "string", "description": "Destination city name" },
          "destinationAirport": { "type": "string", "description": "Destination airport name" },
          "aircraft": { "type": "string", "description": "Aircraft type name" },
          "aircraftCode": { "type": "string", "description": "Aircraft IATA code" },
          "totalSeats": { "type": "integer", "description": "Total number of seats" },
          "cabinClasses": { "type": "array", "items": { "type": "string" }, "description": "Available cabin classes" },
          "url": { "type": "string", "description": "Link to view on FlightSeatMap.com" }
        }
      },
      "SeatmapDetail": {
        "type": "object",
        "properties": {
          "flightNumber": { "type": "string" },
          "airline": { "type": "string" },
          "airlineCode": { "type": "string" },
          "airlineLogo": { "type": "string" },
          "origin": { "type": "string" },
          "originCity": { "type": "string" },
          "originAirport": { "type": "string" },
          "originCountry": { "type": "string" },
          "destination": { "type": "string" },
          "destinationCity": { "type": "string" },
          "destinationAirport": { "type": "string" },
          "destinationCountry": { "type": "string" },
          "aircraft": { "type": "string" },
          "aircraftCode": { "type": "string" },
          "totalSeats": { "type": "integer" },
          "availableSeats": { "type": "integer" },
          "cabins": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string", "description": "Cabin class name (Economy, Business, etc.)" },
                "totalSeats": { "type": "integer" },
                "availableSeats": { "type": "integer" },
                "features": { "type": "array", "items": { "type": "string" }, "description": "Available seat features in this cabin" }
              }
            }
          },
          "decks": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "deck": { "type": "string", "description": "Deck name (main, upper)" },
                "seats": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Seat" }
                }
              }
            }
          },
          "url": { "type": "string", "description": "Link to view interactive seat map on FlightSeatMap.com" }
        }
      },
      "Seat": {
        "type": "object",
        "properties": {
          "number": { "type": "string", "description": "Seat number (e.g. 1A, 23F)" },
          "cabin": { "type": "string", "description": "Cabin class (Economy, Business, etc.)" },
          "available": { "type": "boolean", "description": "Whether seat is available" },
          "features": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Seat features: Window, Aisle, Exit Row, Extra Legroom, Bulkhead, Middle, etc."
          },
          "price": {
            "type": "object",
            "properties": {
              "amount": { "type": "string" },
              "currency": { "type": "string" }
            },
            "description": "Seat price if available"
          }
        }
      },
      "Airline": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "iata": { "type": "string", "description": "IATA airline code" },
          "country": { "type": "string" },
          "logo": { "type": "string", "description": "Airline logo URL" },
          "seatmapCount": { "type": "integer", "description": "Number of aircraft seat maps" },
          "flightCount": { "type": "integer", "description": "Number of flight seat maps" },
          "averageRating": { "type": "number", "description": "Average review rating" },
          "url": { "type": "string", "description": "Link to airline page on FlightSeatMap.com" }
        }
      },
      "AirlineDetail": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "iata": { "type": "string" },
          "icao": { "type": "string" },
          "country": { "type": "string" },
          "active": { "type": "boolean" },
          "logo": { "type": "string" },
          "seatmapCount": { "type": "integer" },
          "flightCount": { "type": "integer" },
          "averageRating": { "type": "number" },
          "reviewsCount": { "type": "integer" },
          "fleet": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "aircraftCode": { "type": "string" },
                "aircraftName": { "type": "string" },
                "totalSeats": { "type": "integer" },
                "cabinClasses": { "type": "array", "items": { "type": "string" } },
                "url": { "type": "string" }
              }
            }
          },
          "routes": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/FlightSummary" }
          },
          "url": { "type": "string" }
        }
      },
      "Airport": {
        "type": "object",
        "properties": {
          "iata": { "type": "string", "description": "Airport IATA code" },
          "name": { "type": "string", "description": "Airport name" },
          "city": { "type": "string", "description": "City name" },
          "country": { "type": "string", "description": "Country name" },
          "latitude": { "type": "number" },
          "longitude": { "type": "number" }
        }
      }
    }
  }
}