FlightSearchResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/flight-mcp-com/json-schema/flight-mcp-com-flight-search-response-schema.json",
  "title": "FlightSearchResponse",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/flight-mcp-com-openapi.yml#/components/schemas/FlightSearchResponse",
  "type": "object",
  "required": [
    "requestId",
    "remainingApiCalls",
    "query",
    "offers",
    "meta"
  ],
  "properties": {
    "requestId": {
      "type": "string"
    },
    "remainingApiCalls": {
      "type": "integer",
      "minimum": 0,
      "description": "Billable API calls remaining in the current UTC month after this request. Cache hits do not reduce this value."
    },
    "query": {
      "$ref": "#/$defs/FlightSearchInput"
    },
    "offers": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/FlightOffer"
      }
    },
    "meta": {
      "type": "object",
      "required": [
        "cached",
        "cacheTtlSeconds",
        "cacheExpiresAt",
        "durationMs",
        "quota"
      ],
      "properties": {
        "cached": {
          "type": "boolean"
        },
        "partial": {
          "type": "boolean",
          "description": "True when at least one upstream search failed. This does not indicate inventory completeness. Omitted for older cached results without coverage metadata."
        },
        "cacheTtlSeconds": {
          "type": "integer"
        },
        "cacheExpiresAt": {
          "type": "string",
          "format": "date-time"
        },
        "durationMs": {
          "type": "integer",
          "minimum": 0
        },
        "quota": {
          "$ref": "#/$defs/Quota"
        }
      }
    }
  },
  "$defs": {
    "FlightItinerary": {
      "type": "object",
      "required": [
        "durationMinutes",
        "stops",
        "segments"
      ],
      "properties": {
        "durationMinutes": {
          "type": "integer",
          "minimum": 1
        },
        "stops": {
          "type": "integer",
          "minimum": 0
        },
        "segments": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/FlightSegment"
          }
        }
      }
    },
    "FlightOffer": {
      "type": "object",
      "required": [
        "id",
        "price",
        "cabinClass",
        "itineraries",
        "fetchedAt"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "price": {
          "type": "object",
          "required": [
            "amountMinor",
            "currency"
          ],
          "properties": {
            "amountMinor": {
              "type": "integer",
              "minimum": 0
            },
            "currency": {
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            }
          }
        },
        "cabinClass": {
          "type": "string",
          "enum": [
            "economy",
            "premium_economy",
            "business",
            "first"
          ]
        },
        "itineraries": {
          "type": "array",
          "minItems": 1,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/FlightItinerary"
          }
        },
        "seatsRemaining": {
          "type": "integer",
          "minimum": 0
        },
        "fetchedAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "FlightSearchInput": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "origin",
        "destination",
        "departureDate"
      ],
      "properties": {
        "origin": {
          "type": "string",
          "pattern": "^[A-Z]{3}$",
          "description": "Airport IATA code, or TYO to search both Haneda (HND) and Narita (NRT)."
        },
        "destination": {
          "type": "string",
          "pattern": "^[A-Z]{3}$",
          "description": "Airport IATA code, or TYO to search both Haneda (HND) and Narita (NRT)."
        },
        "departureDate": {
          "type": "string",
          "format": "date"
        },
        "returnDate": {
          "type": "string",
          "format": "date"
        },
        "adults": {
          "type": "integer",
          "minimum": 1,
          "maximum": 9,
          "default": 1
        },
        "children": {
          "type": "integer",
          "minimum": 0,
          "maximum": 8,
          "default": 0
        },
        "infants": {
          "type": "integer",
          "minimum": 0,
          "maximum": 8,
          "default": 0
        },
        "cabinClass": {
          "type": "string",
          "enum": [
            "economy",
            "premium_economy",
            "business",
            "first"
          ],
          "default": "economy"
        },
        "currency": {
          "type": "string",
          "pattern": "^[A-Z]{3}$",
          "default": "JPY"
        },
        "locale": {
          "type": "string",
          "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$",
          "default": "ja-JP"
        },
        "pointOfSaleCountry": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "default": "JP",
          "description": "Requested sales-country context. Booking results match the requested currency and are not filtered by sales country."
        },
        "maxResults": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        },
        "cacheTtlSeconds": {
          "type": "integer",
          "minimum": 60,
          "maximum": 259200,
          "default": 300
        }
      }
    },
    "FlightSegment": {
      "type": "object",
      "required": [
        "origin",
        "destination",
        "departureAt",
        "arrivalAt",
        "marketingCarrier",
        "flightNumber",
        "durationMinutes"
      ],
      "properties": {
        "origin": {
          "type": "string",
          "pattern": "^[A-Z]{3}$"
        },
        "destination": {
          "type": "string",
          "pattern": "^[A-Z]{3}$"
        },
        "departureAt": {
          "type": "string"
        },
        "arrivalAt": {
          "type": "string"
        },
        "marketingCarrier": {
          "type": "object",
          "required": [
            "code",
            "name"
          ],
          "properties": {
            "code": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          }
        },
        "flightNumber": {
          "type": "string"
        },
        "durationMinutes": {
          "type": "integer",
          "minimum": 1
        },
        "aircraft": {
          "type": "string"
        }
      }
    },
    "Quota": {
      "type": "object",
      "required": [
        "limit",
        "used",
        "remaining",
        "resetAt"
      ],
      "properties": {
        "limit": {
          "type": "integer",
          "minimum": 0
        },
        "used": {
          "type": "integer",
          "minimum": 0
        },
        "remaining": {
          "type": "integer",
          "minimum": 0
        },
        "resetAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}