{
  "openapi": "3.1.0",
  "info": {
    "title": "PropPulse API",
    "description": "Global real estate intelligence API — 11 endpoints covering the full property lifecycle in any country. Mortgage/remortgage analysis, affordability, rent-vs-buy modeling, refinance opportunity, local market intelligence, investment property ROI, AVM property valuation, neighborhood intelligence, first-time-buyer schemes, landlord toolkit, and rental-market intelligence (long-term + short-term + budget/hostel). Every endpoint accepts a global `location` + optional `country`; `zip` still works as a legacy US alias. Jurisdiction-aware for US/UK/CA/AU/DE/IN with honest fallback elsewhere — never silently assumes US. Powered by FRED housing data (US only), Tavily live search, and Claude synthesis. All require x402 micropayment (USDC on Base).",
    "version": "1.3.0",
    "contact": { "url": "https://proppulse.theaslangroupllc.com" }
  },
  "servers": [{ "url": "https://proppulse.theaslangroupllc.com" }],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature. Omit to receive 402 with payment requirements. Sign and retry."
      }
    }
  },
  "security": [{ "x402": [] }],
  "paths": {
    "/api/prop/mortgage": {
      "get": {
        "operationId": "propMortgage",
        "summary": "Mortgage analysis — jurisdiction-aware rates, payment breakdown, max price, lender links",
        "description": "Rate snapshot, monthly payment breakdown, maximum affordable home price, lender options, and rate lock advice — using the buyer's own jurisdiction's mortgage structure (US 30/15yr fixed, UK fixed-deal/remortgage, CA term/amortization, DE Zinsbindung, AU offset, IN floating). Response includes Rocket Mortgage, LendingTree, and Better Mortgage affiliate links (US-focused).",
        "parameters": [
          { "name": "income", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Annual gross income, local currency" },
          { "name": "down", "in": "query", "schema": { "type": "number" }, "description": "Down payment. Defaults to 20%." },
          { "name": "location", "in": "query", "schema": { "type": "string" }, "description": "City, region, or postal code" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country code, e.g. US, UK, CA, DE, AU, IN (optional; unspecified is treated honestly, not silently as US)" },
          { "name": "zip", "in": "query", "schema": { "type": "string" }, "description": "Legacy alias for location; implies country=US when country is omitted" },
          { "name": "debt", "in": "query", "schema": { "type": "number" }, "description": "Existing monthly debt payments (car, student loans)" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Mortgage analysis with rate snapshot, payment breakdown, affordability, and lender links" },
          "400": { "description": "income is required — returned before payment is charged" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with /api/prop/afford for honest affordability ceiling, or /api/prop/first-buyer for down payment assistance programs"
      }
    },
    "/api/prop/afford": {
      "get": {
        "operationId": "propAfford",
        "summary": "True affordability analysis — stress-free vs. lender-qualifying ceiling, jurisdiction-aware",
        "description": "Honest affordability ceiling using the buyer's own jurisdiction's convention (US DTI, UK income multiple, CA GDS/TDS, DE cold/warm rent split, AU serviceability buffer, IN EMI ratio) — not just what a lender approves, but what the buyer can actually sustain. Response includes mortgage lender links for pre-approval (US-focused).",
        "parameters": [
          { "name": "income", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Annual gross income, local currency" },
          { "name": "down", "in": "query", "schema": { "type": "number" }, "description": "Available down payment" },
          { "name": "location", "in": "query", "schema": { "type": "string" }, "description": "City, region, or postal code" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country code, e.g. US, UK, CA, DE, AU, IN (optional)" },
          { "name": "zip", "in": "query", "schema": { "type": "string" }, "description": "Legacy alias for location; implies country=US when country is omitted" },
          { "name": "debt", "in": "query", "schema": { "type": "number" }, "description": "Existing monthly debt payments" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Affordability analysis with thresholds, breakdowns, and lender links" },
          "400": { "description": "income is required — returned before payment is charged" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Use with /api/prop/first-buyer to find down payment assistance if savings are below the floor"
      }
    },
    "/api/prop/rentbuy": {
      "get": {
        "operationId": "propRentBuy",
        "summary": "Rent vs. buy decision model — break-even, 5-year wealth comparison, recommendation",
        "description": "Full rent-vs-buy model with break-even timeline, 5-year net worth comparison, opportunity cost of down payment, equity accrual, and a clear buy/rent/wait recommendation. Transaction-cost assumptions adapt to jurisdiction (stamp duty, Grunderwerbsteuer, agent commissions) when known. Global coverage — any currency and market.",
        "parameters": [
          { "name": "rent", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Current monthly rent in local currency" },
          { "name": "location", "in": "query", "schema": { "type": "string" }, "description": "City, region, or postal code" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country code, e.g. US, UK, CA, DE, AU, IN (optional)" },
          { "name": "savings", "in": "query", "schema": { "type": "number" }, "description": "Available savings / potential down payment" },
          { "name": "years", "in": "query", "schema": { "type": "number" }, "description": "Planned years in home. Defaults to 5." },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Rent vs. buy analysis with break-even, wealth comparison, and recommendation" },
          "400": { "description": "rent is required — returned before payment is charged" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/prop/refi": {
      "get": {
        "operationId": "propRefi",
        "summary": "Refinance/remortgage opportunity — break-even, monthly savings, cash-out potential",
        "description": "Honest refinance/remortgage analysis: break-even timeline, monthly savings, total interest saved, and cash-out option where that concept applies locally. Factors in early-repayment charges / prepayment penalties (UK ERC, DE Vorfälligkeitsentschädigung) that many non-US jurisdictions apply. Response includes lender links (US-focused).",
        "parameters": [
          { "name": "rate", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Current interest rate as percentage (e.g. 7.25)" },
          { "name": "balance", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Remaining loan balance" },
          { "name": "years_left", "in": "query", "schema": { "type": "number" }, "description": "Years remaining on current loan. Defaults to 25." },
          { "name": "home_value", "in": "query", "schema": { "type": "number" }, "description": "Current home value (enables cash-out analysis)" },
          { "name": "location", "in": "query", "schema": { "type": "string" }, "description": "City, region, or postal code" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country code, e.g. US, UK, CA, DE, AU, IN (optional)" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Refinance analysis with break-even, savings, and lender links" },
          "400": { "description": "rate and balance are required — returned before payment is charged" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/prop/market": {
      "get": {
        "operationId": "propMarket",
        "summary": "Local market intelligence — buyer/seller conditions, price trends, inventory, any country",
        "description": "Hyperlocal market intelligence: buyer/seller market rating, market score (0-100), price trend, days on market, months of supply, and concrete briefings for buyers and sellers. National FRED context is US-only and clearly labeled as such for non-US markets — everything else is Tavily-grounded, not fabricated.",
        "parameters": [
          { "name": "location", "in": "query", "required": true, "schema": { "type": "string" }, "description": "City, region, or postal code" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country code, e.g. US, UK, CA, DE, AU, IN (optional)" },
          { "name": "zip", "in": "query", "schema": { "type": "string" }, "description": "Legacy alias for location; implies country=US when country is omitted" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Market intelligence with price trends, supply/demand, and buyer/seller briefings" },
          "400": { "description": "location (or legacy zip) is required — returned before payment is charged" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with /api/prop/neighborhood for a complete area analysis, or /api/prop/valuate for property-specific pricing"
      }
    },
    "/api/prop/invest": {
      "get": {
        "operationId": "propInvest",
        "summary": "Investment property ROI — cap rate, cash-on-cash, 5-year projection, investment grade, any country",
        "description": "Complete investment property analysis: cap rate, cash-on-cash return, gross rent multiplier, price-to-rent ratio, break-even occupancy, 5-year appreciation scenarios, and an A-D investment grade — plus jurisdiction-aware landlord tax flags (UK Section 24, CA no principal-residence exemption on rentals, DE 10yr speculation period, AU negative gearing). Response includes financing/insurance links (US-focused).",
        "parameters": [
          { "name": "location", "in": "query", "required": true, "schema": { "type": "string" }, "example": "Austin, TX" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country code, e.g. US, UK, CA, DE, AU, IN (optional)" },
          { "name": "price", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Purchase price in local currency" },
          { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "single-family / multifamily / condo / short-term", "example": "single-family" },
          { "name": "rent", "in": "query", "schema": { "type": "string" }, "description": "Expected monthly rent — estimated from market data if omitted" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Investment analysis with metrics, grade, projections, and financing links" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with /api/prop/neighborhood for market context, or /api/prop/landlord for local regulations, or /api/prop/rental-market for a dedicated rent-market read"
      }
    },
    "/api/prop/valuate": {
      "get": {
        "operationId": "propValuate",
        "summary": "Property valuation — AVM estimate with comparable sales and negotiation intelligence, any country",
        "description": "AVM-style property valuation using comparable sales and local market data. Returns a value range with confidence level, comparable sales, price-per-sqft context, market trend, and negotiation advice. Never fabricates a foreign country's national house-price-index figure — cites only what Tavily actually found.",
        "parameters": [
          { "name": "address", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Full property address" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country code, e.g. US, UK, CA, DE, AU, IN (optional)" },
          { "name": "sqft", "in": "query", "schema": { "type": "string" }, "description": "Square footage (improves estimate)" },
          { "name": "beds", "in": "query", "schema": { "type": "string" }, "description": "Bed/bath description (e.g. 3/2)" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Property valuation with value range, comps, trend, and negotiation advice" },
          "400": { "description": "address is required — returned before payment is charged" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Follow with /api/prop/neighborhood for area intelligence to support the offer decision"
      }
    },
    "/api/prop/neighborhood": {
      "get": {
        "operationId": "propNeighborhood",
        "summary": "Neighborhood intelligence — schools, safety, walkability, investment outlook, any country",
        "description": "Comprehensive neighborhood profile: school context, safety/crime context, walkability, amenity density, demographic character, and a gentrification-stage assessment. Returns an overall score, strengths, and who the neighborhood is best for. Global — states honestly when a jurisdiction's rating source (school/crime index) wasn't found rather than inventing one.",
        "parameters": [
          { "name": "location", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Neighborhood, city district, or full address", "example": "Boerum Hill, Brooklyn, NY" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country code, e.g. US, UK, CA, DE, AU, IN (optional)" },
          { "name": "zip", "in": "query", "schema": { "type": "string" }, "description": "Legacy alias for location; implies country=US when country is omitted" },
          { "name": "priority", "in": "query", "schema": { "type": "string" }, "description": "schools / investment / walkability / safety / balanced" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Neighborhood profile with scores, school data, safety context, and investment outlook" },
          "400": { "description": "location (or legacy zip) is required — returned before payment is charged" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Chain after /api/prop/valuate for full area + property analysis before making an offer"
      }
    },
    "/api/prop/first-buyer": {
      "get": {
        "operationId": "propFirstBuyer",
        "summary": "First-time homebuyer guide — jurisdiction-real schemes, loan types, step-by-step process",
        "description": "Complete first-time homebuyer guide using the buyer's actual jurisdiction's schemes: US FHA/VA/USDA/DPA, UK Stamp Duty relief + LISA, CA FHSA + RRSP HBP, AU FHOG + FHSSS, and an honest note that Germany has no comparable scheme. Closing cost estimate, hidden costs, credit tips, and a step-by-step timeline. Response includes mortgage lender links (US-focused).",
        "parameters": [
          { "name": "location", "in": "query", "schema": { "type": "string" }, "description": "City, region, or postal code", "example": "Denver, CO" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country code, e.g. US, UK, CA, DE, AU, IN (optional)" },
          { "name": "zip", "in": "query", "schema": { "type": "string" }, "description": "Legacy alias for location; implies country=US when country is omitted" },
          { "name": "income", "in": "query", "schema": { "type": "string" }, "description": "Annual household income — affects program eligibility" },
          { "name": "savings", "in": "query", "schema": { "type": "string" }, "description": "Available savings for down payment" },
          { "name": "credit", "in": "query", "schema": { "type": "string" }, "description": "Credit score range (e.g. 680)" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "First-time buyer guide with real assistance programs, process timeline, and lender links" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.10,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with /api/prop/afford to determine realistic purchase ceiling before starting the process"
      }
    },
    "/api/prop/landlord": {
      "get": {
        "operationId": "propLandlord",
        "summary": "Landlord toolkit — rent pricing, tenant screening, lease law, tax flags, any country",
        "description": "Complete landlord reference for any city or country: rent pricing recommendation, tenant screening process, notice/eviction process and timeline, rent-control status, security deposit limits, maintenance obligations, jurisdiction-aware tax treatment (UK Section 24, DE 10yr speculation period, AU negative gearing), and tool recommendations (Avail/TurboTenant only surfaced for US/unspecified).",
        "parameters": [
          { "name": "location", "in": "query", "required": true, "schema": { "type": "string" }, "description": "City and region/country", "example": "Chicago, IL" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country code, e.g. US, UK, CA, DE, AU, IN (optional)" },
          { "name": "zip", "in": "query", "schema": { "type": "string" }, "description": "Legacy alias for location; implies country=US when country is omitted" },
          { "name": "units", "in": "query", "schema": { "type": "string" }, "description": "Number of rental units" },
          { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "long-term / short-term / furnished" },
          { "name": "situation", "in": "query", "schema": { "type": "string" }, "description": "general / finding-tenants / eviction / raising-rent / maintenance" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Landlord toolkit with rent pricing, screening process, local law, tax flags, and tool links" },
          "400": { "description": "location (or legacy zip) is required — returned before payment is charged" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with /api/prop/invest to evaluate a property before becoming its landlord, or /api/prop/rental-market for market rent context"
      }
    },
    "/api/prop/rental-market": {
      "get": {
        "operationId": "propRentalMarket",
        "summary": "Rental-market intelligence — asking rent, vacancy, rent-control flag, STR + budget/hostel read, any country",
        "description": "Global rental-market read: asking-rent level/trend, vacancy/tightness signal, seasonality, and a deterministic rent-control flag (DE Mietpreisbremse, IE RPZ, NYC/SF/LA stabilization, ON guideline, Scotland caps, FR encadrement). Optional angle adds short-term-rental read + regulation flag (NYC LL18, Barcelona, Amsterdam, Berlin, London, Paris) and budget/hostel rates. When purchase_price is given, computes gross yield (long-term and STR) deterministically in code. Distinct from HomePulse /api/home/rent (single-address fair-rent) and this API's own /api/prop/rentbuy (personal rent-vs-buy decision) and FindPulse /api/find/rental (equipment rental).",
        "parameters": [
          { "name": "location", "in": "query", "required": true, "schema": { "type": "string" }, "example": "Manchester" },
          { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Country code, e.g. US, UK, CA, DE, AU, IN (optional)" },
          { "name": "bedrooms", "in": "query", "schema": { "type": "string" } },
          { "name": "purchase_price", "in": "query", "schema": { "type": "string" }, "description": "Enables deterministic gross-yield math (long-term and, when angle includes STR, short-term)" },
          { "name": "angle", "in": "query", "schema": { "type": "string" }, "description": "renter | investor | str | budget (default: overview — includes all sections)" },
          { "name": "lang", "in": "query", "schema": { "type": "string" } },
          { "name": "PAYMENT-SIGNATURE", "in": "header", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Rental-market read with long-term rent, rent-control flag, optional STR/budget sections, and yield math" },
          "400": { "description": "location is required — returned before payment is charged" },
          "402": { "description": "Payment required" }
        },
        "x-price-usd": 0.12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pair with /api/prop/invest for full investment analysis, or /api/prop/landlord for legal/tax context"
      }
    }
  }
}