{
  "openapi": "3.1.1",
  "info": {
    "title": "KnowMySeat Public Catalog API",
    "version": "1.1.0",
    "description": "Read-only airline, configuration and seat facts. No account or API key required. Select the exact configuration with the traveler; this is not flight assignment, availability, pricing or booking. Preserve returned uncertainty, warnings and measurement units. Successful responses may be cached for 60 seconds; the published-data reader also refreshes within 60 seconds. Unknown values are not zero or absence."
  },
  "servers": [
    {
      "url": "https://knowmyseat.com/api/v1"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "Guide and working examples",
    "url": "https://knowmyseat.com/developers"
  },
  "paths": {
    "/airlines": {
      "get": {
        "operationId": "searchAirlines",
        "summary": "Find airlines by name or code",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            },
            "description": "Airline name/code or aircraft model. Search does not resolve flight numbers."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Maximum returned items."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 999999,
              "default": 0
            },
            "description": "Zero-based result offset. Follow pagination.nextOffset until null."
          }
        ],
        "responses": {
          "200": {
            "description": "Published catalog facts with limitations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string",
                      "const": "1"
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Airline"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "version",
                    "limitations",
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown aircraft, endpoint or passenger seat.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Published data temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/aircraft": {
      "get": {
        "operationId": "searchAircraft",
        "summary": "Find aircraft configurations",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            },
            "description": "Airline name/code or aircraft model. Search does not resolve flight numbers."
          },
          {
            "name": "airline",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9*-]{1,150}$"
            },
            "description": "Airline ID from searchAirlines."
          },
          {
            "name": "seats",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9999
            },
            "description": "Published capacity, not selectable labels or availability. Same-capacity layouts can differ."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Maximum returned items."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 999999,
              "default": 0
            },
            "description": "Zero-based result offset. Follow pagination.nextOffset until null."
          }
        ],
        "responses": {
          "200": {
            "description": "Published catalog facts with limitations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string",
                      "const": "1"
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Aircraft"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "version",
                    "limitations",
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown aircraft, endpoint or passenger seat.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Published data temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/aircraft/{aircraftId}": {
      "get": {
        "operationId": "getAircraft",
        "summary": "Read configuration details and cabin/deck codes",
        "parameters": [
          {
            "name": "aircraftId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9*-]{1,150}$"
            },
            "description": "Exact ID returned by aircraft search. Keep variants separate."
          }
        ],
        "responses": {
          "200": {
            "description": "Published catalog facts with limitations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string",
                      "const": "1"
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "data": {
                      "$ref": "#/components/schemas/AircraftDetail"
                    }
                  },
                  "required": [
                    "version",
                    "limitations",
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown aircraft, endpoint or passenger seat.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Published data temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/aircraft/{aircraftId}/seats": {
      "get": {
        "operationId": "findSeats",
        "summary": "Find passenger seats by cabin, deck and listed preferences",
        "description": "Only listed passenger seats are returned, in natural seat-number order. These are guide matches, not live available seats.",
        "parameters": [
          {
            "name": "aircraftId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9*-]{1,150}$"
            },
            "description": "Exact ID returned by aircraft search. Keep variants separate."
          },
          {
            "name": "cabin",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "F",
                "B",
                "P",
                "E"
              ]
            },
            "description": "Drawing/group code. Read cabinCoverage for actual cabin product names; P can be an extra-legroom Economy product."
          },
          {
            "name": "deck",
            "in": "query",
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,2}$"
            },
            "description": "Deck value from getAircraft. Omit for all decks."
          },
          {
            "name": "require",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "legroom",
                  "space"
                ]
              }
            },
            "description": "Repeat for multiple required listed benefits. All selected requirements apply.",
            "style": "form",
            "explode": true
          },
          {
            "name": "avoid",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "recline",
                  "window",
                  "service",
                  "exit",
                  "crew"
                ]
              }
            },
            "description": "Exclude reported recline/window issues, lavatory/galley proximity, exit rows, or crew-use cautions. Missing notes do not prove absence. Repeat for multiple choices.",
            "style": "form",
            "explode": true
          },
          {
            "name": "minPitch",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 200
            },
            "description": "Minimum listed dimension in inches. Uses seat-specific or cabin values and the lower end of ranges. Unknown, unitless or qualified measurements do not match. Pitch is not clear legroom; bed length is not pitch."
          },
          {
            "name": "minWidth",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 200
            },
            "description": "Minimum listed dimension in inches. Uses seat-specific or cabin values and the lower end of ranges. Unknown, unitless or qualified measurements do not match. Pitch is not clear legroom; bed length is not pitch."
          },
          {
            "name": "equipment",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "power",
                  "ac_power",
                  "usb_power",
                  "wifi",
                  "screen"
                ]
              }
            },
            "description": "Repeat for required equipment; all choices apply. AC socket and USB charging are distinct. Personal screens exclude streaming-only entertainment. Wi-Fi means equipped, not free or guaranteed working. Unknown equipment does not match; cabin defaults, shared power and fees can apply.",
            "style": "form",
            "explode": true
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Maximum returned items."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 999999,
              "default": 0
            },
            "description": "Zero-based result offset. Follow pagination.nextOffset until null."
          }
        ],
        "responses": {
          "200": {
            "description": "Published catalog facts with limitations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string",
                      "const": "1"
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "aircraft": {
                      "$ref": "#/components/schemas/Aircraft"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Seat"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  },
                  "required": [
                    "version",
                    "limitations",
                    "data",
                    "pagination"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown aircraft, endpoint or passenger seat.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Published data temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/aircraft/{aircraftId}/seats/{seat}": {
      "get": {
        "operationId": "getSeat",
        "summary": "Read one seat's dimensions, equipment, benefits and cautions",
        "parameters": [
          {
            "name": "aircraftId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9*-]{1,150}$"
            },
            "description": "Exact ID returned by aircraft search. Keep variants separate."
          },
          {
            "name": "seat",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,3}[A-Za-z]{0,2}$"
            },
            "description": "A passenger label returned by findSeats, such as 12B. Numeric-only labels are supported."
          }
        ],
        "responses": {
          "200": {
            "description": "Published catalog facts with limitations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string",
                      "const": "1"
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "aircraft": {
                      "$ref": "#/components/schemas/Aircraft"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Seat"
                    }
                  },
                  "required": [
                    "version",
                    "limitations",
                    "aircraft",
                    "data"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown aircraft, endpoint or passenger seat.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Published data temporarily unavailable; retry later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "limit": {
            "type": "integer",
            "minimum": 0
          },
          "offset": {
            "type": "integer",
            "minimum": 0
          },
          "nextOffset": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          }
        },
        "required": [
          "total",
          "limit",
          "offset",
          "nextOffset"
        ]
      },
      "Airline": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "code": {
            "type": [
              "string",
              "null"
            ]
          },
          "configurations": {
            "type": "integer",
            "minimum": 0
          },
          "guideUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "id",
          "name",
          "guideUrl"
        ]
      },
      "Cabin": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "seats": {
            "type": "integer",
            "minimum": 0
          },
          "pitch": {
            "type": "string"
          },
          "width": {
            "type": "string"
          },
          "recline": {
            "type": "string"
          },
          "bedLength": {
            "type": "string"
          }
        }
      },
      "Aircraft": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "airline": {
            "$ref": "#/components/schemas/Airline"
          },
          "model": {
            "type": "string"
          },
          "variant": {
            "type": "string"
          },
          "airlineConfigurationCode": {
            "type": [
              "string",
              "null"
            ]
          },
          "collectedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "listedCapacity": {
            "type": "integer",
            "minimum": 0
          },
          "mappedPassengerSeats": {
            "type": "integer",
            "minimum": 0
          },
          "layoutStatus": {
            "type": "string",
            "enum": [
              "matched",
              "matched-blocked",
              "partial",
              "unavailable",
              "source-conflict"
            ]
          },
          "cabinMismatch": {
            "type": "boolean"
          },
          "conditionalCabins": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "category": {
                  "type": "string"
                }
              }
            }
          },
          "cabins": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Cabin"
            }
          },
          "cabinCoverage": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "name": {
                  "type": "string"
                },
                "listed": {
                  "type": "integer",
                  "minimum": 0
                },
                "mapped": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "guideUrl": {
            "type": "string"
          },
          "apiUrl": {
            "type": "string"
          },
          "seatsUrl": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "airline",
          "variant",
          "listedCapacity",
          "mappedPassengerSeats",
          "warnings",
          "guideUrl"
        ]
      },
      "AircraftDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Aircraft"
          },
          {
            "type": "object",
            "properties": {
              "decks": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "cabinCodes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "blockedPositions": {
                "type": "integer",
                "minimum": 0
              }
            }
          }
        ]
      },
      "Seat": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "cabinCode": {
            "type": "string"
          },
          "cabin": {
            "type": "string"
          },
          "deck": {
            "type": "string"
          },
          "dimensions": {
            "type": "object",
            "properties": {
              "pitch": {
                "type": "string"
              },
              "width": {
                "type": "string"
              },
              "recline": {
                "type": "string"
              },
              "bedLength": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "note": {
                "type": "string"
              }
            }
          },
          "amenities": {
            "type": "object",
            "properties": {
              "wifi": {
                "type": "string"
              },
              "entertainment": {
                "type": "string"
              },
              "power": {
                "type": "string"
              }
            }
          },
          "guidance": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "benefits": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "cautions": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "guideUrl": {
            "type": "string"
          }
        },
        "required": [
          "label",
          "cabin",
          "dimensions",
          "amenities",
          "guidance",
          "guideUrl"
        ]
      }
    }
  }
}