{
  "openapi": "3.1.0",
  "info": {
    "title": "PointCast Real Estate Observatory",
    "version": "1.0.0",
    "description": "Public source-backed educational research and pure hypothetical calculations. Read only; no investment orders, accounts, applications, credentials or external transactions."
  },
  "servers": [
    {
      "url": "https://pointcast.xyz"
    }
  ],
  "paths": {
    "/real-estate.json": {
      "get": {
        "operationId": "realEstateStudy",
        "summary": "Read the versioned study, source ledger, snapshots and model schema",
        "responses": {
          "200": {
            "description": "Educational study"
          }
        }
      }
    },
    "/real-estate/methodology.json": {
      "get": {
        "operationId": "realEstateMethodology",
        "summary": "Read methodology, exclusions and sources",
        "responses": {
          "200": {
            "description": "Methodology"
          }
        }
      }
    },
    "/api/real-estate/query": {
      "get": {
        "operationId": "queryRealEstate",
        "summary": "Search representative study markets",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "region",
            "in": "query",
            "schema": {
              "enum": [
                "all",
                "local",
                "global"
              ]
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Local property-type filter only; global markets are jurisdiction comparisons.",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Filtered local/global research"
          },
          "400": {
            "description": "Invalid query"
          }
        }
      }
    },
    "/api/real-estate/scenario": {
      "get": {
        "operationId": "calculateRealEstate",
        "summary": "Calculate five hypothetical years in three scenarios",
        "parameters": [
          {
            "name": "capital",
            "in": "query",
            "description": "Hypothetical starting capital. USD Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 100000000,
              "default": 250000
            }
          },
          {
            "name": "annualContribution",
            "in": "query",
            "description": "Annual cash contribution. USD Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 10000000,
              "default": 30000
            }
          },
          {
            "name": "purchasePrice",
            "in": "query",
            "description": "Illustrative property price. USD Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 100000000,
              "default": 650000
            }
          },
          {
            "name": "downPaymentPct",
            "in": "query",
            "description": "Down payment. % Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 100,
              "default": 35
            }
          },
          {
            "name": "interestRate",
            "in": "query",
            "description": "Fixed annual mortgage rate. % Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 40,
              "default": 6.5
            }
          },
          {
            "name": "loanYears",
            "in": "query",
            "description": "Amortization term. years Illustrative assumptions.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 30
            }
          },
          {
            "name": "monthlyRent",
            "in": "query",
            "description": "Illustrative monthly scheduled rent. USD Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 1000000,
              "default": 5200
            }
          },
          {
            "name": "vacancyPct",
            "in": "query",
            "description": "Vacancy and collection loss. % Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 100,
              "default": 5
            }
          },
          {
            "name": "propertyTax",
            "in": "query",
            "description": "Annual property tax. USD Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 10000000,
              "default": 8125
            }
          },
          {
            "name": "insurance",
            "in": "query",
            "description": "Annual insurance. USD Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 10000000,
              "default": 2400
            }
          },
          {
            "name": "repairs",
            "in": "query",
            "description": "Annual repairs and maintenance. USD Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 10000000,
              "default": 3000
            }
          },
          {
            "name": "managementPct",
            "in": "query",
            "description": "Management share of collected rent. % Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 100,
              "default": 8
            }
          },
          {
            "name": "capexReserveAnnual",
            "in": "query",
            "description": "Annual capex budget. USD Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 10000000,
              "default": 3000
            }
          },
          {
            "name": "closingCostPct",
            "in": "query",
            "description": "Acquisition closing costs. % Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 25,
              "default": 3
            }
          },
          {
            "name": "reserveMonths",
            "in": "query",
            "description": "Initial liquidity reserve. months Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 36,
              "default": 6
            }
          },
          {
            "name": "rentGrowthPct",
            "in": "query",
            "description": "Annual rent growth. % Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": -50,
              "maximum": 50,
              "default": 3
            }
          },
          {
            "name": "appreciationPct",
            "in": "query",
            "description": "Annual property value change. % Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": -50,
              "maximum": 50,
              "default": 3
            }
          },
          {
            "name": "expenseGrowthPct",
            "in": "query",
            "description": "Annual expense growth. % Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": -50,
              "maximum": 50,
              "default": 3
            }
          },
          {
            "name": "sellingCostPct",
            "in": "query",
            "description": "Illustrative sale costs. % Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 25,
              "default": 6
            }
          },
          {
            "name": "minDscr",
            "in": "query",
            "description": "Minimum acquisition DSCR. ratio Illustrative assumptions.",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 5,
              "default": 1.25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Three scenarios with yearly acquisition gates, cashflow, debt, reserves and equity"
          },
          "400": {
            "description": "Invalid, unknown, duplicate, empty or out-of-range numeric input"
          }
        }
      }
    },
    "/api/real-estate/feed": {
      "get": {
        "operationId": "readRealEstateFeed",
        "summary": "Explicitly fetch fixed FHFA or USGS public source, with dated snapshot fallback",
        "parameters": [
          {
            "name": "source",
            "in": "query",
            "required": true,
            "schema": {
              "enum": [
                "fhfa",
                "usgs"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "fetched, cached or snapshot-fallback; observation/generation time distinct from retrieval time"
          },
          "400": {
            "description": "Invalid source"
          }
        }
      }
    }
  }
}