{
  "openapi": "3.1.0",
  "info": {
    "title": "LUXSKI Snow Concierge API",
    "description": "API for accessing real-time ski resort snow conditions, SnowSure™ ratings, and luxury hotel information from LUXSKI.",
    "version": "1.0.0",
    "contact": {
      "name": "LUXSKI",
      "email": "hello@luxski.com",
      "url": "https://www.lux.ski"
    }
  },
  "servers": [
    {
      "url": "https://www.lux.ski/api/gpt",
      "description": "LUXSKI Production API"
    }
  ],
  "paths": {
    "/destinations": {
      "get": {
        "operationId": "getDestinations",
        "summary": "Get all ski destinations with SnowSure™ scores",
        "description": "Returns a list of ski resorts with current snow conditions, SnowSure™ ratings, and forecasts. Use this to find resorts with the best conditions.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "country",
            "in": "query",
            "description": "Filter by country name (e.g., 'Switzerland', 'France', 'USA')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "region",
            "in": "query",
            "description": "Filter by region (e.g., 'Alps', 'Rocky Mountains')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minScore",
            "in": "query",
            "description": "Minimum SnowSure™ score (0-100). Use 65 for 'Very Good' or better, 80 for 'Excellent'",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort order for results",
            "schema": {
              "type": "string",
              "enum": ["score", "snow24h", "forecast", "name"],
              "default": "score"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of ski destinations with snow data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DestinationsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/destination/{slug}": {
      "get": {
        "operationId": "getDestination",
        "summary": "Get detailed information about a specific ski resort",
        "description": "Returns comprehensive data about a ski resort including current conditions, forecast, historical comparison, and associated luxury hotels.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The resort slug (e.g., 'verbier', 'zermatt', 'aspen-mountain')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed destination data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DestinationDetail"
                }
              }
            }
          },
          "404": {
            "description": "Destination not found"
          }
        }
      }
    },
    "/recommendations": {
      "get": {
        "operationId": "getRecommendations",
        "summary": "Get AI-curated ski resort recommendations",
        "description": "Returns top recommended ski resorts based on current conditions, recent snowfall, and forecasts. Only includes resorts with 'Very Good' or 'Excellent' SnowSure™ ratings.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "description": "Type of recommendation",
            "schema": {
              "type": "string",
              "enum": ["snowsure", "powder", "forecast"],
              "default": "snowsure"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of recommendations to return",
            "schema": {
              "type": "integer",
              "default": 5,
              "maximum": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Resort recommendations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecommendationsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/hotels": {
      "get": {
        "operationId": "getHotels",
        "summary": "Get luxury ski hotels",
        "description": "Returns a list of curated luxury ski hotels with ratings, amenities, and location information.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "country",
            "in": "query",
            "description": "Filter by country",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "resort",
            "in": "query",
            "description": "Filter by ski resort name",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minStars",
            "in": "query",
            "description": "Minimum star rating (1-5)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5
            }
          },
          {
            "name": "designHotels",
            "in": "query",
            "description": "Show only Design Hotels",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "michelinKeys",
            "in": "query",
            "description": "Show only hotels with Michelin Keys",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "skiInSkiOut",
            "in": "query",
            "description": "Show only ski-in/ski-out hotels",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of hotels",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HotelsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/search": {
      "get": {
        "operationId": "search",
        "summary": "Search destinations and hotels",
        "description": "Search across all ski destinations and luxury hotels by name, location, country, or description.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filter results by type",
            "schema": {
              "type": "string",
              "enum": ["all", "destinations", "hotels"],
              "default": "all"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DestinationsResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer"
          },
          "updated": {
            "type": "string",
            "format": "date-time"
          },
          "destinations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DestinationSummary"
            }
          }
        }
      },
      "DestinationSummary": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "snowSure": {
            "type": "object",
            "properties": {
              "score": {
                "type": "integer",
                "description": "SnowSure™ score from 0-100"
              },
              "rating": {
                "type": "string",
                "enum": ["Excellent", "Very Good", "Good", "Fair", "Poor"]
              },
              "trend": {
                "type": "string",
                "enum": ["up", "down", "stable"]
              }
            }
          },
          "currentConditions": {
            "type": "object",
            "properties": {
              "temperatureC": {
                "type": "number"
              },
              "snowDepthBaseCm": {
                "type": "number"
              },
              "freshSnow24hCm": {
                "type": "number"
              },
              "seasonTotalCm": {
                "type": "number"
              }
            }
          },
          "forecast": {
            "type": "object",
            "properties": {
              "next14DaysCm": {
                "type": "number"
              }
            }
          }
        },
        "example": {
          "name": "Zermatt",
          "slug": "zermatt",
          "url": "https://www.lux.ski/destinations/zermatt",
          "country": "Switzerland",
          "snowSure": {
            "score": 78,
            "rating": "Excellent",
            "trend": "up"
          },
          "currentConditions": {
            "temperatureC": -8,
            "snowDepthBaseCm": 145,
            "freshSnow24hCm": 15,
            "seasonTotalCm": 420
          },
          "forecast": {
            "next14DaysCm": 65
          }
        }
      },
      "DestinationDetail": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "url": { "type": "string" },
          "country": { "type": "string" },
          "description": { "type": "string" },
          "snowSure": {
            "type": "object",
            "properties": {
              "score": { "type": "integer", "description": "SnowSure™ score 0-100" },
              "rating": { "type": "string" },
              "trend": { "type": "string", "enum": ["up", "down", "stable"] },
              "analysis": { "type": "string", "description": "AI-generated conditions analysis" }
            }
          },
          "currentConditions": {
            "type": "object",
            "properties": {
              "temperatureC": { "type": "number" },
              "snowDepthCm": { "type": "number" },
              "freshSnow24hCm": { "type": "number" },
              "freshSnow7DaysCm": { "type": "number" },
              "seasonTotalCm": { "type": "number" },
              "windSpeedKmh": { "type": "number" }
            }
          },
          "forecast": {
            "type": "object",
            "properties": {
              "next14DaysCm": { "type": "number" },
              "dailyForecast": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "date": { "type": "string", "format": "date" },
                    "tempHighC": { "type": "number" },
                    "tempLowC": { "type": "number" },
                    "snowCm": { "type": "number" },
                    "condition": { "type": "string" }
                  }
                }
              }
            }
          },
          "resortInfo": {
            "type": "object",
            "properties": {
              "totalRuns": { "type": "integer" },
              "totalLifts": { "type": "integer" },
              "skiableAcres": { "type": "number" },
              "baseElevationM": { "type": "number" },
              "summitElevationM": { "type": "number" },
              "verticalDropM": { "type": "number" },
              "annualSnowfallCm": { "type": "number" }
            }
          },
          "luxuryHotels": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/HotelSummary" }
          }
        },
        "example": {
          "name": "Zermatt",
          "slug": "zermatt",
          "url": "https://www.lux.ski/destinations/zermatt",
          "country": "Switzerland",
          "snowSure": {
            "score": 78,
            "rating": "Excellent",
            "trend": "up",
            "analysis": "Outstanding conditions with deep base and consistent snowfall."
          },
          "currentConditions": {
            "temperatureC": -8,
            "snowDepthCm": 145,
            "freshSnow24hCm": 15,
            "freshSnow7DaysCm": 48,
            "seasonTotalCm": 420,
            "windSpeedKmh": 12
          },
          "forecast": {
            "next14DaysCm": 65
          },
          "resortInfo": {
            "totalRuns": 200,
            "totalLifts": 52,
            "skiableAcres": 890,
            "baseElevationM": 1620,
            "summitElevationM": 3883,
            "verticalDropM": 2263
          }
        }
      },
      "RecommendationItem": {
        "type": "object",
        "properties": {
          "rank": { "type": "integer" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "url": { "type": "string" },
          "country": { "type": "string" },
          "snowSureScore": { "type": "integer" },
          "snowSureRating": { "type": "string" },
          "whyRecommended": { "type": "string" },
          "freshSnow24hCm": { "type": "number" },
          "forecastCm": { "type": "number" }
        },
        "example": {
          "rank": 1,
          "name": "Jackson Hole",
          "slug": "jackson-hole-mountain-resort",
          "url": "https://www.lux.ski/destinations/jackson-hole-mountain-resort",
          "country": "USA",
          "snowSureScore": 82,
          "snowSureRating": "Excellent",
          "whyRecommended": "30cm of fresh powder in 24h with another 45cm forecast",
          "freshSnow24hCm": 30,
          "forecastCm": 45
        }
      },
      "RecommendationsResponse": {
        "type": "object",
        "properties": {
          "recommendationType": { "type": "string" },
          "description": { "type": "string" },
          "recommendations": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/RecommendationItem" }
          }
        }
      },
      "HotelSummary": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "url": { "type": "string" },
          "location": { "type": "string" },
          "country": { "type": "string" },
          "nearestSkiResort": { "type": "string" },
          "starRating": { "type": "integer" },
          "numberOfRooms": { "type": "integer" },
          "distanceToLifts": { "type": "string" },
          "tripAdvisorScore": { "type": "number" },
          "michelinKeys": { "type": "integer" },
          "isDesignHotel": { "type": "boolean" }
        },
        "example": {
          "name": "Cheval Blanc Courchevel",
          "url": "https://www.lux.ski/hotels/europe/courchevel-1850/cheval-blanc-courchevel",
          "location": "Courchevel 1850, France",
          "country": "France",
          "nearestSkiResort": "Courchevel 1850",
          "starRating": 5,
          "numberOfRooms": 36,
          "distanceToLifts": "Ski-in/Ski-out",
          "tripAdvisorScore": 4.9,
          "michelinKeys": 3,
          "isDesignHotel": false
        }
      },
      "HotelsResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer"
          },
          "hotels": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HotelSummary"
            }
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "totalResults": { "type": "integer" },
          "results": {
            "type": "object",
            "properties": {
              "destinations": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "slug": { "type": "string" },
                    "url": { "type": "string" },
                    "country": { "type": "string" },
                    "snowSureScore": { "type": "integer" },
                    "matchedOn": { "type": "string" }
                  }
                }
              },
              "hotels": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "url": { "type": "string" },
                    "location": { "type": "string" },
                    "nearestSkiResort": { "type": "string" },
                    "starRating": { "type": "integer" },
                    "matchedOn": { "type": "string" }
                  }
                }
              }
            }
          }
        },
        "example": {
          "query": "zermatt",
          "totalResults": 5,
          "results": {
            "destinations": [
              {
                "name": "Zermatt",
                "slug": "zermatt",
                "url": "https://www.lux.ski/destinations/zermatt",
                "country": "Switzerland",
                "snowSureScore": 78,
                "matchedOn": "name"
              }
            ],
            "hotels": [
              {
                "name": "The Omnia",
                "url": "https://www.lux.ski/hotels/europe/zermatt/the-omnia",
                "location": "Zermatt, Switzerland",
                "nearestSkiResort": "Zermatt",
                "starRating": 5,
                "matchedOn": "resort"
              }
            ]
          }
        }
      }
    }
  }
}