{
  "openapi": "3.1.0",
  "info": {
    "title": "Flight MCP API",
    "version": "0.1.0",
    "description": "Normalized flight search over REST. Cache hits do not consume monthly plan calls."
  },
  "servers": [{ "url": "https://flight-mcp.com" }],
  "paths": {
    "/healthz": {
      "get": {
        "summary": "Service health",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is available",
            "content": { "application/json": { "schema": { "type": "object", "required": ["status", "service", "version"], "properties": { "status": { "const": "ok" }, "service": { "type": "string" }, "version": { "type": "string" } } } } }
          }
        }
      }
    },
    "/v1/flights/search": {
      "post": {
        "summary": "Search normalized flight offers",
        "operationId": "searchFlights",
        "security": [{ "bearerAuth": [] }, { "apiKeyHeader": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlightSearchInput" } } }
        },
        "responses": {
          "200": {
            "description": "Flight offers",
            "headers": {
              "ratelimit-limit": { "schema": { "type": "integer" }, "description": "Monthly plan limit" },
              "ratelimit-remaining": { "schema": { "type": "integer" }, "description": "Monthly calls remaining" },
              "ratelimit-reset": { "schema": { "type": "integer" }, "description": "Seconds until reset" },
              "x-ratelimit-reset": { "schema": { "type": "integer" }, "description": "Reset time in Unix seconds" },
              "x-request-id": { "schema": { "type": "string" } }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlightSearchResponse" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "500": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "503": { "$ref": "#/components/responses/Error" },
          "504": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer" },
      "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key" }
    },
    "schemas": {
      "FlightSearchInput": {
        "type": "object",
        "additionalProperties": false,
        "required": ["origin", "destination", "departureDate"],
        "properties": {
          "origin": { "type": "string", "pattern": "^[A-Z]{3}$", "examples": ["HND"] },
          "destination": { "type": "string", "pattern": "^[A-Z]{3}$", "examples": ["SFO"] },
          "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" },
          "maxResults": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 },
          "cacheTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 259200, "default": 300 }
        }
      },
      "FlightSearchResponse": {
        "type": "object",
        "required": ["requestId", "query", "offers", "meta"],
        "properties": {
          "requestId": { "type": "string" },
          "query": { "$ref": "#/components/schemas/FlightSearchInput" },
          "offers": { "type": "array", "items": { "$ref": "#/components/schemas/FlightOffer" } },
          "meta": {
            "type": "object",
            "required": ["cached", "cacheTtlSeconds", "cacheExpiresAt", "durationMs", "quota"],
            "properties": {
              "cached": { "type": "boolean" },
              "cacheTtlSeconds": { "type": "integer" },
              "cacheExpiresAt": { "type": "string", "format": "date-time" },
              "durationMs": { "type": "integer", "minimum": 0 },
              "quota": { "$ref": "#/components/schemas/Quota" }
            }
          }
        }
      },
      "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": "#/components/schemas/FlightItinerary" } },
          "seatsRemaining": { "type": "integer", "minimum": 0 },
          "fetchedAt": { "type": "string", "format": "date-time" }
        }
      },
      "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": "#/components/schemas/FlightSegment" } }
        }
      },
      "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" }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "requestId"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "requestId": { "type": "string" },
              "details": {}
            }
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "API error",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }
      }
    }
  }
}