{
  "openapi": "3.1.0",
  "info": {
    "title": "Timeshare Rootz Global",
    "description": "AI-native timeshare resale marketplace. Search 7,000+ listings across 960+ resorts. Government data from FL DBPR and CFPB consumer complaints. Cross-references listing data with registration and complaint records.",
    "version": "0.1.0"
  },
  "servers": [
    { "url": "https://timeshare.rootz.global" }
  ],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchTimeshares",
        "summary": "Search timeshare listings by resort, brand, state, price, bedrooms, exchange network",
        "parameters": [
          { "name": "resort", "in": "query", "schema": { "type": "string" }, "description": "Resort name (partial match)" },
          { "name": "brand", "in": "query", "schema": { "type": "string", "enum": ["Marriott", "Wyndham", "Hilton", "Disney", "Hyatt", "Bluegreen", "Westgate", "Holiday Inn", "Vistana/Marriott", "Ritz-Carlton"] }, "description": "Timeshare brand" },
          { "name": "state", "in": "query", "schema": { "type": "string" }, "description": "US state name (e.g. Florida, Hawaii)" },
          { "name": "city", "in": "query", "schema": { "type": "string" }, "description": "City name (partial match)" },
          { "name": "price_min", "in": "query", "schema": { "type": "integer" }, "description": "Minimum price" },
          { "name": "price_max", "in": "query", "schema": { "type": "integer" }, "description": "Maximum price" },
          { "name": "bedrooms", "in": "query", "schema": { "type": "integer" }, "description": "Number of bedrooms" },
          { "name": "exchange", "in": "query", "schema": { "type": "string" }, "description": "Exchange network (RCI, Interval International)" },
          { "name": "ownership", "in": "query", "schema": { "type": "string" }, "description": "Ownership type (Deeded, Right to Use)" },
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Full-text search across resort, city, state, description" },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["price", "viability", "value"] }, "description": "Sort order: price (cheapest first, default), viability (best investment grade first), value (highest fee coverage ratio first)" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Max results" },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" }
        ],
        "responses": { "200": { "description": "Search results with total count" } }
      }
    },
    "/api/resort/{name}": {
      "get": {
        "operationId": "getResort",
        "summary": "Get resort detail with listings, FL DBPR registration, and payment history",
        "parameters": [
          { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resort name (use + for spaces)" }
        ],
        "responses": { "200": { "description": "Resort detail with listings and government data" } }
      }
    },
    "/api/listing/{id}": {
      "get": {
        "operationId": "getListing",
        "summary": "Get individual listing detail with CFPB complaints for that brand",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Listing ID or source ad number" }
        ],
        "responses": { "200": { "description": "Listing detail with related complaints" } }
      }
    },
    "/api/brands": {
      "get": {
        "operationId": "listBrands",
        "summary": "List all timeshare brands with listing counts, price ranges, and resort counts",
        "responses": { "200": { "description": "Brand summary array" } }
      }
    },
    "/api/resorts": {
      "get": {
        "operationId": "listResorts",
        "summary": "List resorts with listing summaries, filterable by state or brand",
        "parameters": [
          { "name": "state", "in": "query", "schema": { "type": "string" } },
          { "name": "brand", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } }
        ],
        "responses": { "200": { "description": "Resort listing summaries" } }
      }
    },
    "/api/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Get database statistics including brand and state distributions",
        "responses": { "200": { "description": "Database statistics" } }
      }
    },
    "/api/dbpr/projects": {
      "get": {
        "operationId": "searchDBPR",
        "summary": "Search FL DBPR registered timeshare projects by name or county",
        "parameters": [
          { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Project name (partial match)" },
          { "name": "county", "in": "query", "schema": { "type": "string" }, "description": "Florida county name" }
        ],
        "responses": { "200": { "description": "DBPR registered projects" } }
      }
    },
    "/api/dbpr/payments/{projectNumber}": {
      "get": {
        "operationId": "getPaymentHistory",
        "summary": "Get FL DBPR payment/billing history for a timeshare project (5 years)",
        "parameters": [
          { "name": "projectNumber", "in": "path", "required": true, "schema": { "type": "string" }, "description": "DBPR project number (e.g. PR2016)" }
        ],
        "responses": { "200": { "description": "Payment history records" } }
      }
    },
    "/api/complaints": {
      "get": {
        "operationId": "searchComplaints",
        "summary": "Search CFPB consumer complaints for timeshare companies",
        "parameters": [
          { "name": "company", "in": "query", "schema": { "type": "string" }, "description": "Company name (partial match)" },
          { "name": "state", "in": "query", "schema": { "type": "string" }, "description": "Consumer state" }
        ],
        "responses": { "200": { "description": "CFPB complaint records" } }
      }
    },
    "/api/orientation": {
      "get": {
        "operationId": "getOrientation",
        "summary": "Pre-computed context for AI agents — tells you what data is available and how to query it",
        "responses": { "200": { "description": "Orientation context with sample queries" } }
      }
    },
    "/api/viability": {
      "get": {
        "operationId": "getViability",
        "summary": "Find timeshares by rental viability grade. Grade A = likely cashflow positive, B = fee coverage probable, C = lifestyle asset only, D = economically weak. Returns rental estimates, fee coverage ratio, 10-year true cost, and price explanation.",
        "parameters": [
          { "name": "grade", "in": "query", "schema": { "type": "string", "enum": ["A", "B", "C", "D"] }, "description": "Viability grade filter" },
          { "name": "brand", "in": "query", "schema": { "type": "string" }, "description": "Filter by brand" },
          { "name": "state", "in": "query", "schema": { "type": "string" }, "description": "Filter by state" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 }, "description": "Max results" }
        ],
        "responses": { "200": { "description": "Listings with rental economics and viability grades" } }
      }
    },
    "/api/economics/{id}": {
      "get": {
        "operationId": "getEconomics",
        "summary": "Full rental economics for a single listing — rental estimates (low/mid/high), annual carry cost, fee coverage ratio, viability score/grade, true 10-year cost, price explanation, photos, and description",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Listing ID or source ad number" }
        ],
        "responses": { "200": { "description": "Complete economic analysis of one listing" } }
      }
    }
  }
}